@bongos/core 1.19.1081 → 1.20.1

package/modules/render-deploy/routes/act.js

@@ -0,0 +1,88 @@
+'use strict';
+
+// modules/render-deploy/routes/act.js — POST /render-deploy/act: deploy, or roll back (task 1004270).
+//
+//   { action: 'deploy' | 'rollback', deployId?, confirm: true, expectLiveDeployId }
+//   with the owner's key in x-render-key.
+//
+// TWO STEPS, NEVER ONE, AND THE SERVER HOLDS THE SECOND (the /deploy door works the same way,
+// ADR 0293 D4). Step one is the page showing what would happen and what it costs; step two is
+// this request, which is refused unless it says `confirm: true` AND names the deploy that was
+// live when the page drew step one. If Render's live deploy has moved since, the press is
+// refused (409) and nothing is sent, so a confirm can never act on a picture that went stale.
+// A rollback also has to name a deploy that is in this service's own list and was once live and
+// then replaced; a deploy id from anywhere else is refused before any write.
+//
+// Gated on `core.pin.move` (see routes/app.js): the owner's hard gate over what runs for users.
+// The one Render client has no delete, so neither act can remove anything on the owner's account.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { DEPLOY_RE, getApp, statusWords, ROLLBACK_STATUSES } = require('../deploys');
+const { defaultMakeClient, keyFrom, refusal, renderFailure, NEEDS_KEY } = require('../render');
+
+const log = api.logger('render-deploy');
+
+module.exports = function buildRenderDeployActRouter({ makeClient = defaultMakeClient, pool } = {}) {
+  const router = express.Router();
+
+  router.post('/render-deploy/act', api.requireBuilder, api.requirePermission('core.pin.move'), async (req, res) => {
+    const db = pool || api.pool;
+    // Shape only, and strict: an undeclared field is refused. `confirm` and `expectLiveDeployId`
+    // are left to the checks below so each gets its own plain refusal rather than a schema one.
+    if (api.validateOrRespond(req, res, {
+      action: { type: 'string', maxLength: 16 },
+      deployId: { type: 'string', maxLength: 80 },
+      confirm: {},
+      expectLiveDeployId: {},
+    })) return;
+    const body = req.body || {};
+    const action = body.action;
+    if (action !== 'deploy' && action !== 'rollback') return refusal(res, 400, 'bad_action', 'Say whether to deploy or roll back.');
+    if (body.confirm !== true) return refusal(res, 400, 'confirm_needed', 'Nothing was done. Confirm the step you were shown first.');
+    const expect = body.expectLiveDeployId;
+    if (expect !== null && !(typeof expect === 'string' && DEPLOY_RE.test(expect))) {
+      return refusal(res, 400, 'expectation_needed', 'Say which deploy was live when you were shown this step.');
+    }
+    if (action === 'rollback' && !(typeof body.deployId === 'string' && DEPLOY_RE.test(body.deployId))) {
+      return refusal(res, 400, 'bad_deploy_id', 'Say which deploy to roll back to.');
+    }
+    const key = keyFrom(req);
+    if (!key) return refusal(res, 400, 'render_key_needed', NEEDS_KEY);
+    try {
+      const app = await getApp(db);
+      if (!app) return refusal(res, 409, 'not_connected', 'This project is not connected to a Render service yet.');
+      const client = makeClient({ key, ownerId: app.owner_id });
+      const deploys = await client.listDeploys(app.service_id, { limit: 30 });
+      const liveNow = (deploys.find((d) => d.status === 'live') || {}).id || null;
+      if (liveNow !== expect) {
+        return refusal(res, 409, 'stale_history', 'What is live on Render changed since you were shown this step. Nothing was done. Read the history again.');
+      }
+      let started;
+      if (action === 'rollback') {
+        const target = deploys.find((d) => d.id === body.deployId);
+        if (!target) return refusal(res, 404, 'deploy_not_found', 'That deploy is not in this service\'s history.');
+        if (target.id === liveNow) return refusal(res, 409, 'already_live', 'That deploy is already the one running.');
+        if (!ROLLBACK_STATUSES.includes(target.status)) {
+          return refusal(res, 409, 'not_rollbackable', `That deploy cannot be rolled back to (${statusWords(target.status).toLowerCase()}). Only a deploy that ran and was then replaced can.`);
+        }
+        started = await client.rollbackTo(app.service_id, target.id);
+      } else {
+        started = await client.triggerDeploy(app.service_id);
+      }
+      // Confirmed on Render's side: read the service's newest deploy back rather than trust the
+      // 2xx alone, and hand it to the page as what Render says now.
+      let render = null;
+      try {
+        const after = await client.listDeploys(app.service_id, { limit: 3 });
+        const newest = after[0];
+        if (newest) render = { deployId: newest.id, status: newest.status, statusWords: statusWords(newest.status) };
+      } catch (e) { log.warn('read-back after the act failed'); }
+      res.json({ ok: true, action, started: { deployId: (started && started.id) || null }, render });
+    } catch (e) {
+      renderFailure(res, e, log);
+    }
+  });
+
+  return router;
+};

package/modules/render-deploy/routes/app.js

@@ -0,0 +1,65 @@
+'use strict';
+
+// modules/render-deploy/routes/app.js — which Render service this hall manages (task 1004270).
+//
+//   GET /render-deploy/app   the connected workspace + service (two ids, nothing secret), or null
+//   PUT /render-deploy/app   connect one: { ownerId, serviceId } with the owner's key in x-render-key
+//
+// GATED ON `core.pin.move`, the atom the npm-release deploy page and the hall's /deploy gate
+// use: the owner's hard gate over what is running for users. An atom, not requireRank:
+// tests/government_require_permission.mjs fails a new requireRank in a modules/*/routes gate.
+//
+// CONNECT NAMES THE WORKSPACE, IT NEVER PICKS IT. The owner types the workspace id; the key's
+// own workspace list (Render's GET /owners) is used for one thing only, to check the workspace
+// they named is one the key can act in. The service is then read through the client's ownerId
+// guard, so a service in any other workspace is refused before a row is written.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { OWNER_RE, SERVICE_RE, getApp, saveApp } = require('../deploys');
+const { defaultMakeClient, keyFrom, refusal, renderFailure, NEEDS_KEY } = require('../render');
+
+const log = api.logger('render-deploy');
+
+module.exports = function buildRenderDeployAppRouter({ makeClient = defaultMakeClient, pool } = {}) {
+  const router = express.Router();
+  const db = () => pool || api.pool;
+
+  router.get('/render-deploy/app', api.requireBuilder, api.requirePermission('core.pin.move'), async (req, res) => {
+    try {
+      const app = await getApp(db());
+      res.json({ app: app ? { ownerId: app.owner_id, serviceId: app.service_id, serviceName: app.service_name } : null });
+    } catch (e) {
+      log.error(`app read failed: ${e && e.message}`);
+      refusal(res, 500, 'app_read_failed', 'Could not read which Render service this project is connected to.');
+    }
+  });
+
+  router.put('/render-deploy/app', api.requireBuilder, api.requirePermission('core.pin.move'), async (req, res) => {
+    if (api.validateOrRespond(req, res, {
+      ownerId: { type: 'string', maxLength: 80 },
+      serviceId: { type: 'string', maxLength: 80 },
+    })) return;
+    const body = req.body || {};
+    const ownerId = typeof body.ownerId === 'string' ? body.ownerId.trim() : '';
+    const serviceId = typeof body.serviceId === 'string' ? body.serviceId.trim() : '';
+    if (!OWNER_RE.test(ownerId)) return refusal(res, 400, 'bad_owner_id', 'The workspace id looks like tea-… or usr-…. Copy it from Render.');
+    if (!SERVICE_RE.test(serviceId)) return refusal(res, 400, 'bad_service_id', 'The service id looks like srv-…. Copy it from the service page in Render.');
+    const key = keyFrom(req);
+    if (!key) return refusal(res, 400, 'render_key_needed', NEEDS_KEY);
+    try {
+      const client = makeClient({ key, ownerId });
+      const owners = await client.listOwners();
+      if (!owners.some((o) => o.id === ownerId)) {
+        return refusal(res, 403, 'workspace_not_reachable', 'That Render key cannot act in the workspace you named, so nothing was connected.');
+      }
+      const service = await client.getService(serviceId);
+      const saved = await saveApp(db(), { ownerId, serviceId, serviceName: service && service.name, builderId: req.builder && req.builder.id });
+      res.json({ app: { ownerId: saved.owner_id, serviceId: saved.service_id, serviceName: saved.service_name } });
+    } catch (e) {
+      renderFailure(res, e, log);
+    }
+  });
+
+  return router;
+};

package/modules/render-deploy/routes/history.js

@@ -0,0 +1,38 @@
+'use strict';
+
+// modules/render-deploy/routes/history.js — GET /render-deploy/history (task 1004270).
+//
+// The service's Render deploys, each with its commit and the Bongos tasks in it, and which one
+// is live. READ-ONLY: nothing here writes to Render or to the ledger. Gated on `core.pin.move`
+// like the page it feeds (see routes/app.js), because it discloses what is running and on which
+// plan. With no key it answers `needsKey` and the connected app rather than an error, so the page
+// can draw the field that asks for one.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { getApp, readHistory } = require('../deploys');
+const { defaultMakeClient, keyFrom, refusal, renderFailure } = require('../render');
+
+const log = api.logger('render-deploy');
+
+module.exports = function buildRenderDeployHistoryRouter({ makeClient = defaultMakeClient, pool } = {}) {
+  const router = express.Router();
+
+  router.get('/render-deploy/history', api.requireBuilder, api.requirePermission('core.pin.move'), async (req, res) => {
+    const db = pool || api.pool;
+    try {
+      const app = await getApp(db);
+      if (!app) return res.json({ connected: false });
+      const key = keyFrom(req);
+      if (!key) return res.json({ connected: true, needsKey: true, app: { ownerId: app.owner_id, serviceId: app.service_id, serviceName: app.service_name } });
+      const client = makeClient({ key, ownerId: app.owner_id });
+      res.json({ connected: true, needsKey: false, ...(await readHistory({ pool: db, client, app })) });
+    } catch (e) {
+      if (e && (e.name === 'RenderOwnerMismatch' || e.name === 'RenderApiError')) return renderFailure(res, e, log);
+      log.error(`history read failed: ${e && e.message}`);
+      refusal(res, 500, 'history_failed', 'Could not read the deploy history.');
+    }
+  });
+
+  return router;
+};

package/modules/specialities/db.js

@@ -18,19 +18,20 @@ const exec = (executor) => executor || ((text, params) => pool.query(text, param
 const COLUMNS = `id, slug, name, discipline, summary, contract_md,
                  owner_kind, owner_builder_id, owner_project_id,
                  visibility, sellable, offered, offered_by, offered_at,
-                 created_by, created_at, updated_at`;
+                 skills, created_by, created_at, updated_at`;
 
 async function createSpeciality(row, executor) {
   const q = exec(executor);
   const r = await q(
     `INSERT INTO specialities_catalog
        (slug, name, discipline, summary, contract_md, owner_kind,
-        owner_builder_id, owner_project_id, visibility, sellable, created_by)
-     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)
+        owner_builder_id, owner_project_id, visibility, sellable, created_by, skills)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12)
      RETURNING ${COLUMNS}`,
     [row.slug, row.name, row.discipline, row.summary || '', row.contract_md || '',
       row.owner_kind, row.owner_builder_id || null, row.owner_project_id || null,
-      row.visibility || 'private', !!row.sellable, row.created_by || null],
+      row.visibility || 'private', !!row.sellable, row.created_by || null,
+      Array.isArray(row.skills) ? row.skills : []],
   );
   return r.rows[0] || null;
 }
@@ -61,7 +62,7 @@ async function listVisibleTo({ builderId, projectIds = [], discipline = null },
 // A speciality's DISCIPLINE IS IMMUTABLE and is not in this list on purpose:
 // moving one between crafts would silently re-scope everyone who adopted it, and
 // the adoption rows carry a denormalised copy the migration relies on.
-const UPDATABLE = ['name', 'summary', 'contract_md', 'visibility', 'sellable'];
+const UPDATABLE = ['name', 'summary', 'contract_md', 'visibility', 'sellable', 'skills'];
 
 async function updateSpeciality(id, patch, executor) {
   const q = exec(executor);
@@ -174,12 +175,29 @@ async function adopt({ builderId, specialityId, discipline }, executor) {
      VALUES ($1,$2,$3,TRUE)
      ON CONFLICT (builder_id, speciality_id)
        DO UPDATE SET active = TRUE, discipline = EXCLUDED.discipline, adopted_at = now()
-     RETURNING builder_id, speciality_id, discipline, active, adopted_at`,
+     RETURNING builder_id, speciality_id, discipline, active, adopted_at, enabled_skills`,
     [builderId, specialityId, discipline],
   );
   return r.rows[0] || null;
 }
 
+// An adopter's ENABLED skills (task 1004072). Written only on the caller's own
+// ACTIVE adoption: a skill is chosen for a speciality you hold, and a speciality
+// you set down keeps its choices but cannot be edited until you take it up again.
+// The route has already checked every name against the offered set and the
+// instance (specialities.enabledSkillsErrors); this only stores the decision.
+// Returns null when there is no active adoption to write to.
+async function setEnabledSkills(builderId, specialityId, skills, executor) {
+  const q = exec(executor);
+  const r = await q(
+    `UPDATE specialities_adoptions SET enabled_skills = $3
+      WHERE builder_id = $1 AND speciality_id = $2 AND active
+      RETURNING builder_id, speciality_id, discipline, active, adopted_at, enabled_skills`,
+    [builderId, specialityId, skills],
+  );
+  return r.rows[0] || null;
+}
+
 async function abandon(builderId, specialityId, executor) {
   const q = exec(executor);
   const r = await q(
@@ -209,7 +227,8 @@ async function listAdoptions(builderId, executor) {
     // contract_md is HERE because the session-injection port builds the injected
     // fragment from this row — omitting it silently dropped the expert's own terms
     // and left only the name and summary reaching the session.
-    `SELECT s.id, s.slug, s.name, s.discipline, s.summary, s.contract_md, a.active, a.adopted_at
+    `SELECT s.id, s.slug, s.name, s.discipline, s.summary, s.contract_md, s.skills, a.active, a.adopted_at,
+            a.enabled_skills
        FROM specialities_adoptions a JOIN specialities_catalog s ON s.id = a.speciality_id
       WHERE a.builder_id = $1 ORDER BY a.adopted_at DESC`,
     [builderId],
@@ -269,5 +288,5 @@ module.exports = {
   createSpeciality, getSpeciality, listVisibleTo, updateSpeciality,
   addDocument, listDocuments, getDocument, deleteDocument,
   linkLearning, countTraining,
-  adopt, abandon, deactivateCraft, activeForCraft, listAdoptions,
+  adopt, abandon, deactivateCraft, activeForCraft, listAdoptions, setEnabledSkills,
 };

package/modules/specialities/migrations/specialities_003_skills.sql

@@ -0,0 +1,46 @@
+-- specialities_003_skills.sql — a speciality OFFERS skills, and each adopter
+-- turns them on for themselves (task 1004072, part 1 of 3 of ADR 0310).
+--
+-- TWO LAYERS, because one layer is the blanket the owner ruled against
+-- (2026-09-19: "if say two people are economist ideator specialists, then they
+-- decide which skills they want to use ... It does not become super blanketed"):
+--
+--   specialities_catalog.skills            what this speciality OFFERS
+--   specialities_adoptions.enabled_skills  what THIS builder turned on
+--
+-- `skills`, not `offered_skills`: `offered` on the catalog already means "the
+-- project recommends this speciality" (specialities_002), a different fact.
+--
+-- A NEW ADOPTION'S ENABLED SET IS EMPTY, AND THAT IS THE STORED DEFAULT, not a
+-- UI default. The owner's second ruling: "They should be off, and you should
+-- walk through what comes with each." A column default of '{}' makes that true
+-- for every adoption however it is created, including one written by a script.
+-- Existing adoptions get the same empty set, which is correct: nobody has been
+-- walked through anything yet.
+--
+-- NAMING A SKILL GRANTS NOTHING (ADR 0310 §1). These are menus and choices; a
+-- skill is still materialised and permitted by the machinery that always did.
+-- Which names are real is checked where the instance's skills are known (the
+-- route, modules/specialities/skills.js), not here: the set changes on deploy.
+--
+-- Bounded for the reason contract_md is: the enabled set is named in every
+-- session that holds a claim in the craft (part 3), so it is a standing cost.
+-- Additive and forward-safe: old code neither reads nor writes either column.
+
+ALTER TABLE specialities_catalog
+  ADD COLUMN IF NOT EXISTS skills TEXT[] NOT NULL DEFAULT '{}';
+
+ALTER TABLE specialities_catalog
+  DROP CONSTRAINT IF EXISTS specialities_catalog_skills_bounded;
+ALTER TABLE specialities_catalog
+  ADD CONSTRAINT specialities_catalog_skills_bounded
+  CHECK (cardinality(skills) <= 24);
+
+ALTER TABLE specialities_adoptions
+  ADD COLUMN IF NOT EXISTS enabled_skills TEXT[] NOT NULL DEFAULT '{}';
+
+ALTER TABLE specialities_adoptions
+  DROP CONSTRAINT IF EXISTS specialities_adoptions_enabled_skills_bounded;
+ALTER TABLE specialities_adoptions
+  ADD CONSTRAINT specialities_adoptions_enabled_skills_bounded
+  CHECK (cardinality(enabled_skills) <= 24);

package/modules/specialities/routes/specialities.js

@@ -25,6 +25,18 @@ const crypto = require('node:crypto');
 const api = require('../../../src/module-api');
 const S = require('../specialities');
 const db = require('../db');
+const skillsLib = require('../skills');
+
+// The skills this instance has (task 1004072), resolved through the doorway's
+// roots and module predicate, never a core require. Cached briefly inside
+// skills.js because the set only changes on deploy.
+function installedSkills() {
+  return skillsLib.installedSkillsCached({
+    coreRoot: api.resolveCoreRoot(),
+    instanceRoot: api.resolveInstanceRoot(),
+    isModuleEnabled: (key) => api.isModuleEnabled(key),
+  });
+}
 
 const { validateOrRespond, parseId, asyncHandler } = api;
 
@@ -160,6 +172,7 @@ module.exports = function buildSpecialitiesRouter() {
       contract_md: { type: 'string', maxLength: S.LIMITS.CONTRACT },
       visibility: { type: 'string', maxLength: 16 },
       sellable: { type: 'boolean' },
+      skills: { type: 'array', maxItems: S.LIMITS.SKILLS, itemsType: 'string' },
     })) return;
 
     const b = req.body || {};
@@ -173,12 +186,13 @@ module.exports = function buildSpecialitiesRouter() {
       contract_md: b.contract_md || '',
       visibility: b.visibility || 'private',
       sellable: !!b.sellable,
+      skills: Array.isArray(b.skills) ? b.skills : [],
       owner_kind: ownerKind,
       owner_builder_id: builder.id,
       owner_project_id: null,
     };
 
-    const check = S.validateDraft(draft, { disciplines: api.enabledDisciplines() });
+    const check = S.validateDraft(draft, { disciplines: api.enabledDisciplines(), installedSkills: installedSkills() });
     if (!check.ok) return res.fail('validation_failed', { status: 400, details: { errors: check.errors } });
 
     draft.slug = S.slugify(draft.name);
@@ -205,6 +219,7 @@ module.exports = function buildSpecialitiesRouter() {
       contract_md: { type: 'string', maxLength: S.LIMITS.CONTRACT },
       visibility: { type: 'string', maxLength: 16 },
       sellable: { type: 'boolean' },
+      skills: { type: 'array', maxItems: S.LIMITS.SKILLS, itemsType: 'string' },
     })) return;
 
     const projectId = String(req.params.projectId);
@@ -226,12 +241,13 @@ module.exports = function buildSpecialitiesRouter() {
       contract_md: b.contract_md || '',
       visibility: b.visibility || 'private',
       sellable: !!b.sellable,
+      skills: Array.isArray(b.skills) ? b.skills : [],
       owner_kind: 'project',
       owner_builder_id: null,
       owner_project_id: projectId,
     };
 
-    const check = S.validateDraft(draft, { disciplines: api.enabledDisciplines() });
+    const check = S.validateDraft(draft, { disciplines: api.enabledDisciplines(), installedSkills: installedSkills() });
     if (!check.ok) return res.fail('validation_failed', { status: 400, details: { errors: check.errors } });
 
     draft.slug = S.slugify(draft.name);
@@ -287,6 +303,7 @@ module.exports = function buildSpecialitiesRouter() {
       contract_md: { type: 'string', maxLength: S.LIMITS.CONTRACT },
       visibility: { type: 'string', maxLength: 16 },
       sellable: { type: 'boolean' },
+      skills: { type: 'array', maxItems: S.LIMITS.SKILLS, itemsType: 'string' },
     })) return;
 
     const s = await db.getSpeciality(id);
@@ -304,7 +321,11 @@ module.exports = function buildSpecialitiesRouter() {
     }
 
     const merged = { ...s, ...req.body };
-    const check = S.validateDraft(merged, { disciplines: api.enabledDisciplines() });
+    // The offered set is re-checked only when this edit SENDS it (task 1004072):
+    // a skill removed from the instance since must not block renaming the
+    // speciality, while a new list is held to what exists now.
+    if (!req.body || req.body.skills === undefined) merged.skills = undefined;
+    const check = S.validateDraft(merged, { disciplines: api.enabledDisciplines(), installedSkills: installedSkills() });
     if (!check.ok) return res.fail('validation_failed', { status: 400, details: { errors: check.errors } });
 
     res.json({ speciality: await db.updateSpeciality(id, req.body || {}) });
@@ -380,6 +401,33 @@ module.exports = function buildSpecialitiesRouter() {
     res.json({ adoption });
   }));
 
+  // PUT /specialities/:id/skills — the caller's ENABLED set for a speciality they
+  // hold (task 1004072, ADR 0310 §2). Replaces the set whole: the walkthrough
+  // (task 1004073) sends the decisions it collected, so a partial patch would
+  // leave a skill switched on that the person was never shown again. Own
+  // adoption only, and only while active. Every name must be offered by the
+  // speciality AND exist here. rank: any builder, on their own row only.
+  router.put('/specialities/:id/skills', api.requireBuilder, asyncHandler('PUT /specialities/:id/skills', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      enabled_skills: { required: true, type: 'array', maxItems: S.LIMITS.SKILLS, itemsType: 'string' },
+    })) return;
+    const s = await db.getSpeciality(id);
+    if (!s || !(await visibleTo(s, req.builder))) return res.fail('not_found', 404);
+    const requested = req.body.enabled_skills;
+    const errors = S.enabledSkillsErrors(requested, s, installedSkills());
+    if (errors.length) return res.fail('validation_failed', { status: 400, details: { errors } });
+    const adoption = await db.setEnabledSkills(req.builder.id, id, requested);
+    if (!adoption) {
+      return res.fail('not_adopted', {
+        status: 409,
+        message: 'Adopt this speciality first — skills are chosen for a speciality you hold.',
+      });
+    }
+    res.json({ adoption });
+  }));
+
   router.post('/specialities/:id/abandon', api.requireBuilder, asyncHandler('POST /specialities/:id/abandon', async (req, res) => {
     const id = parseId(req, res, { code: 'bad_id' });
     if (id === null) return;

package/modules/specialities/skills.js

@@ -0,0 +1,94 @@
+// modules/specialities/skills.js — the skills THIS instance actually has, read
+// from disk (task 1004072; ADR 0310 §"What this is NOT": "a speciality may name
+// only skills the instance actually has").
+//
+// WHY FROM DISK. A skill is a directory holding a SKILL.md, in three places:
+// the core's .claude/skills/, the instance's own .claude/skills/ (a split-root
+// instance keeps its authored skills beside its config), and each ENABLED
+// module's modules/<key>/skills/ (task 1003321, the tree claude-materialize
+// lands into a checkout). Those three are exactly what a session on this
+// instance can be handed, so they are the vocabulary a speciality may offer from.
+// A disabled module's skills are not the instance's, so they are left out: a
+// speciality offering one would walk a newcomer through a skill that 404s.
+//
+// NAMING A SKILL GRANTS NOTHING (ADR 0310 §1). This file only answers "does it
+// exist"; nothing here materialises a skill or widens what anyone may run.
+//
+// The roots and the module predicate are INJECTED, so a test can hand it a temp
+// tree and the route hands it the doorway's resolvers. Every read fails soft to
+// "not here": an unreadable directory contributes no skills rather than
+// throwing out of a request, and the validator treats an absent skill as
+// unknown, which is the fail-closed reading.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// The same allowlist claude-materialize applies to a skill directory name:
+// lowercase, digits, hyphen. A name outside it is never a skill here.
+const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+function listDirs(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch { return []; }
+}
+
+// The description line from a SKILL.md's frontmatter, for the adoption
+// walkthrough (task 1004073) to show. Flat `description: ...` only, the grammar
+// every SKILL.md here uses; anything else reads as no description.
+function readDescription(skillMd) {
+  try {
+    const text = fs.readFileSync(skillMd, 'utf8');
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (!fm) return '';
+    const line = fm[1].split(/\r?\n/).find((l) => /^description:\s*/.test(l));
+    if (!line) return '';
+    return line.replace(/^description:\s*/, '').replace(/^(['"])([\s\S]*)\1$/, '$2').trim();
+  } catch { return ''; }
+}
+
+function collect(out, dir, source) {
+  for (const name of listDirs(dir)) {
+    if (!SKILL_NAME_RE.test(name) || out.has(name)) continue;
+    const md = path.join(dir, name, 'SKILL.md');
+    if (!fs.existsSync(md)) continue;
+    out.set(name, { name, description: readDescription(md), source });
+  }
+}
+
+/**
+ * The skills this instance has: Map name -> { name, description, source }.
+ * First root wins on a duplicate name (core, then instance, then modules), the
+ * precedence materialisation uses.
+ */
+function installedSkills({ coreRoot, instanceRoot = null, isModuleEnabled = () => false } = {}) {
+  const out = new Map();
+  const roots = [...new Set([coreRoot, instanceRoot].filter(Boolean))];
+  for (const root of roots) collect(out, path.join(root, '.claude', 'skills'), root === coreRoot ? 'core' : 'instance');
+  for (const root of roots) {
+    const modulesDir = path.join(root, 'modules');
+    for (const key of listDirs(modulesDir)) {
+      let on = false;
+      try { on = isModuleEnabled(key) === true; } catch { on = false; }
+      if (on) collect(out, path.join(modulesDir, key, 'skills'), `module:${key}`);
+    }
+  }
+  return out;
+}
+
+// A short-lived cache, because the set changes only on deploy and every
+// authoring write and skills read asks for it. 60s bounds how long a skill that
+// was just removed can still be offered.
+let cached = null;
+const TTL_MS = 60 * 1000;
+function installedSkillsCached(opts, now = Date.now()) {
+  if (cached && now - cached.at < TTL_MS) return cached.map;
+  const map = installedSkills(opts);
+  cached = { at: now, map };
+  return map;
+}
+function _resetCache() { cached = null; }
+
+module.exports = { SKILL_NAME_RE, installedSkills, installedSkillsCached, readDescription, _resetCache };

package/modules/specialities/specialities.js

@@ -1,5 +1,5 @@
 // modules/specialities/specialities.js — role SUB-SPECIALITIES: a named bundle of
-// knowledge, skills (ADR 0310 — decided, NOT yet built) and an interaction contract that sits UNDER a craft
+// knowledge, skills (ADR 0310 — offered and enabled sets, task 1004072) and an interaction contract that sits UNDER a craft
 // (task 1003855, goal 1000095; ADR 0296).
 //
 // WHAT THIS IS FOR. A craft says how you work (engineer / ideator / artist / ui).
@@ -14,12 +14,13 @@
 //                                  resolved into GET /me and injected by the
 //                                  Conductor hook — a speciality contract rides
 //                                  that SAME path, it does not add a second one
-//   • declared skills              NOT BUILT. Decided in ADR 0310 (task 1003978)
-//                                  and deliberately not implemented there: a speciality
-//                                  will OFFER skills, and each adopter enables them one
-//                                  at a time after being shown what each does. Nothing
-//                                  in this file, the schema or the routes carries it yet —
-//                                  `grep -i skill` here finds only prose.
+//   • declared skills              ADR 0310, part 1 built in task 1004072: a speciality
+//                                  OFFERS skills (`skills`), each adopter's ENABLED set
+//                                  starts empty (`enabled_skills`), and only a skill this
+//                                  instance has may be named (skills.js). The walkthrough
+//                                  that fills the enabled set is task 1004073; the session
+//                                  line naming it is task 1004074. Naming a skill grants
+//                                  nothing.
 // The genuinely new part is the knowledge bundle, which is why the migration adds
 // tables for it and this file carries the rules over them.
 //
@@ -45,8 +46,50 @@ const LIMITS = {
   DOC_TITLE: 200,
   DOC_BODY: 100000,
   DOCS_PER_SPECIALITY: 200,
+  // Mirrors the cardinality CHECKs in specialities_003. A standing cost: the
+  // enabled set is named in every session holding a claim in the craft.
+  SKILLS: 24,
 };
 
+const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+// The shape and existence rules for a list of skill names, shared by the
+// offered set (validateDraft) and an adopter's enabled set (enabledSkillsErrors).
+// `installed` is the set of names this instance has (skills.js), passed IN so
+// the rule stays pure. It is REQUIRED whenever the list is non-empty: a list
+// nothing checked is refused, never admitted (fail-closed, ADR 0310 "a speciality
+// may name only skills the instance actually has").
+function skillListErrors(list, field, installed) {
+  const errors = [];
+  if (list == null) return errors;
+  if (!Array.isArray(list)) { errors.push({ field, code: 'invalid', expected: 'array of skill names' }); return errors; }
+  if (list.length > LIMITS.SKILLS) errors.push({ field, code: 'too_many', max: LIMITS.SKILLS });
+  const bad = list.filter((n) => typeof n !== 'string' || !SKILL_NAME_RE.test(n));
+  if (bad.length) errors.push({ field, code: 'invalid_name', names: bad.map(String) });
+  const seen = new Set(); const dup = [];
+  for (const n of list) { if (seen.has(n)) dup.push(n); seen.add(n); }
+  if (dup.length) errors.push({ field, code: 'duplicate', names: [...new Set(dup)] });
+  if (list.length && !(installed instanceof Set || installed instanceof Map)) {
+    errors.push({ field, code: 'uncheckable' });
+  } else if (list.length) {
+    const unknown = list.filter((n) => typeof n === 'string' && SKILL_NAME_RE.test(n) && !installed.has(n));
+    if (unknown.length) errors.push({ field, code: 'unknown_skill', names: unknown });
+  }
+  return errors;
+}
+
+// An adopter's ENABLED set: every name must be offered by the speciality AND
+// exist on this instance. Offered-but-since-removed is refused too — enabling a
+// skill that 404s is the dead end ADR 0310 names.
+function enabledSkillsErrors(requested, speciality, installed) {
+  const errors = skillListErrors(requested, 'enabled_skills', installed);
+  if (!Array.isArray(requested)) return errors;
+  const offered = new Set((speciality && Array.isArray(speciality.skills)) ? speciality.skills : []);
+  const notOffered = requested.filter((n) => typeof n === 'string' && !offered.has(n));
+  if (notOffered.length) errors.push({ field: 'enabled_skills', code: 'not_offered', names: notOffered });
+  return errors;
+}
+
 // A slug is derived, never asked for: the authoring surface takes a human name
 // and this makes it addressable. Unique PER OWNER, so two experts may both own
 // an "economics" — see the migration's partial indexes.
@@ -64,7 +107,7 @@ function slugify(name) {
 // discipline-modes.json plus whatever enabled modules contribute
 // (enabledDisciplines()), so it is a runtime value and hardcoding it here would
 // silently reject a module-contributed craft like `ui`.
-function validateDraft(draft, { disciplines } = {}) {
+function validateDraft(draft, { disciplines, installedSkills = null } = {}) {
   const errors = [];
   const d = draft || {};
   const name = String(d.name || '').trim();
@@ -112,6 +155,10 @@ function validateDraft(draft, { disciplines } = {}) {
     errors.push({ field: 'visibility', code: 'project_needs_project_owner' });
   }
 
+  // The skills this speciality OFFERS (task 1004072). Only names this instance
+  // has; checked here so authoring gets a field-level refusal.
+  errors.push(...skillListErrors(d.skills, 'skills', installedSkills));
+
   const ownerKind = d.owner_kind;
   if (ownerKind !== 'builder' && ownerKind !== 'project') {
     errors.push({ field: 'owner_kind', code: 'invalid', allowed: ['builder', 'project'] });
@@ -229,4 +276,4 @@ function offeredTo(specialities, viewer, adoptions = []) {
   });
 }
 
-module.exports = { VISIBILITIES, LIMITS, slugify, validateDraft, canAdopt, describeForApi, offeredTo };
+module.exports = { VISIBILITIES, LIMITS, SKILL_NAME_RE, slugify, validateDraft, skillListErrors, enabledSkillsErrors, canAdopt, describeForApi, offeredTo };

package/modules/ui-design/kit/fixtures/me-cross-project-private.json

@@ -0,0 +1,12 @@
+{
+  "hide_stats": true,
+  "profile_state": "provisional",
+  "account_visibility": "private",
+  "recruiter_discoverable": null,
+  "recruiter_discoverable_effective": false,
+  "handle": "builder",
+  "display_name": null,
+  "bio": null,
+  "links": null,
+  "cross_project": null
+}