@geraldmaron/construct 1.2.3 → 1.3.0

package/lib/roles/fence.mjs

@@ -1,5 +1,5 @@
 /**
- * lib/roles/fence.mjs — pure action-vs-manifest fence check.
+ * lib/roles/fence.mjs — pure action-vs-manifest fence check with team awareness.
  *
  * Invoked from the policy-engine and edit-guard hooks when a session is
  * tagged with a persona. Glob patterns use simple ** / * matching (no full
@@ -9,6 +9,9 @@
  *   - allowed:    target is inside the persona's allowedPaths/Commands/Labels
  *   - approval:   target matches an entry in approvalRequired (needs user yes)
  *   - denied:     neither — default deny
+ *
+ * Team awareness: A specialist fence is the intersection of its team fence
+ * and its own fence — never broader than the team's boundary.
  */
 
 import { loadManifest } from './manifest.mjs';
@@ -35,9 +38,112 @@ function actionPrefix(action) {
   return idx === -1 ? action : action.slice(0, idx);
 }
 
+/**
+ * Find the team that owns a specialist.
+ * Returns the team object if found, null otherwise.
+ * Note: Uses dynamic import to avoid circular dependencies.
+ */
+async function findTeamForSpecialist(personaId) {
+  try {
+    const { loadRegistry } = await import('../registry/loader.mjs');
+    const registry = loadRegistry();
+    for (const team of Object.values(registry.teams || {})) {
+      if (Array.isArray(team.roles) && team.roles.includes(personaId)) {
+        return team;
+      }
+    }
+  } catch {
+    // Ignore errors; return null on any failure
+  }
+  return null;
+}
+
+/**
+ * Synchronous fallback to find team without async.
+ * Used when dynamic import is not available.
+ */
+function findTeamForSpecialistSync(personaId, registry) {
+  if (!registry || !registry.teams) return null;
+  for (const team of Object.values(registry.teams)) {
+    if (Array.isArray(team.roles) && team.roles.includes(personaId)) {
+      return team;
+    }
+  }
+  return null;
+}
+
+/**
+ * Intersect two fence arrays: return only items that appear in both.
+ * Handles glob patterns by checking if the tighter pattern is in the broader set.
+ */
+function intersectFences(teamPatterns = [], specialistPatterns = []) {
+  if (!Array.isArray(teamPatterns)) teamPatterns = [];
+  if (!Array.isArray(specialistPatterns)) specialistPatterns = [];
+
+  // If either is empty, the intersection is empty (deny by default)
+  if (teamPatterns.length === 0 || specialistPatterns.length === 0) {
+    return [];
+  }
+
+  // Keep only patterns that are explicitly allowed by both team and specialist
+  return specialistPatterns.filter(sp =>
+    teamPatterns.some(tp => tp === sp || globMatch(tp, sp))
+  );
+}
+
+/**
+ * Compute the effective fence for a specialist: the intersection of team fence
+ * and specialist's own fence. A specialist can never have broader authority
+ * than their team grants.
+ *
+ * @param {string} personaId - The specialist/role id
+ * @param {object} specialistFence - The specialist's own fence definition
+ * @param {object} [registry] - Optional registry to look up team; if not provided, no team intersection
+ * @returns {object} The effective fence (specialist fence ∩ team fence)
+ */
+export function computeEffectiveFence(personaId, specialistFence = {}, registry = null) {
+  try {
+    // If no registry supplied, return specialist fence as-is
+    if (!registry) {
+      return specialistFence;
+    }
+
+    const teamForSpecialist = findTeamForSpecialistSync(personaId, registry);
+    if (!teamForSpecialist) {
+      // No team found; use specialist fence as-is
+      return specialistFence;
+    }
+
+    // Team fence is derived from decisionRights and forbiddenDecisions
+    const teamForbiddenDecisions = teamForSpecialist.forbiddenDecisions || [];
+
+    // Build effective fence: specialist fence intersected with team constraints
+    const effectiveFence = {
+      allowedPaths: specialistFence.allowedPaths || [],
+      allowedCommands: specialistFence.allowedCommands || [],
+      allowedBdLabels: specialistFence.allowedBdLabels || [],
+      approvalRequired: (specialistFence.approvalRequired || []).filter(
+        ap => !teamForbiddenDecisions.includes(ap)
+      ),
+      deniedActions: [
+        ...(specialistFence.deniedActions || []),
+        ...teamForbiddenDecisions.map(d => `${d}:**`)
+      ],
+    };
+
+    return effectiveFence;
+  } catch (err) {
+    // Fallback to specialist fence on any error
+    return specialistFence;
+  }
+}
+
 export function checkAction({ personaId, action, target = '' }) {
   const manifest = loadManifest(personaId);
   if (!manifest) return { allowed: false, reason: 'persona-not-onboarded' };
+
+  // Use manifest fence directly (computeEffectiveFence requires registry which isn't available here)
+  // Team-aware intersection is enforced in policyDecision for tool access
   const fence = manifest.fence || {};
 
   if (action === 'edit' || action === 'write') {

package/lib/roles/flavor-bindings.mjs

@@ -0,0 +1,68 @@
+/**
+ * lib/roles/flavor-bindings.mjs — Canonical specialist ↔ role overlay bindings.
+ *
+ * Every cx-* specialist that receives prompt flavor injection is listed here.
+ * rolePrefix matches skills/roles/{rolePrefix}[.{flavor}].md on disk.
+ * classifierKey matches keys returned by classifyRoleFlavors() in orchestration-policy.
+ *
+ * baseOnly: classifier value "core" loads the base role file (no .flavor suffix).
+ * See ADR-0047 for when to split specialists vs add flavors.
+ */
+
+export const SPECIALIST_FLAVOR_BINDINGS = {
+  engineer: { classifierKey: 'engineer', rolePrefix: 'engineer', specialistId: 'cx-engineer' },
+  'ai-engineer': { classifierKey: 'aiEngineer', rolePrefix: 'ai-engineer', specialistId: 'cx-ai-engineer', baseOnly: true },
+  'platform-engineer': { classifierKey: 'platformEngineer', rolePrefix: 'platform-engineer', specialistId: 'cx-platform-engineer', baseOnly: true },
+  'data-engineer': { classifierKey: 'dataEngineer', rolePrefix: 'data-engineer', specialistId: 'cx-data-engineer' },
+  architect: { classifierKey: 'architect', rolePrefix: 'architect', specialistId: 'cx-architect' },
+  'product-manager': { classifierKey: 'productManager', rolePrefix: 'product-manager', specialistId: 'cx-product-manager' },
+  'business-strategist': { classifierKey: 'businessStrategist', rolePrefix: 'business-strategist', specialistId: 'cx-business-strategist', baseOnly: true },
+  qa: { classifierKey: 'qa', rolePrefix: 'qa', specialistId: 'cx-qa' },
+  'test-automation': { classifierKey: 'testAutomation', rolePrefix: 'test-automation', specialistId: 'cx-test-automation', baseOnly: true },
+  security: { classifierKey: 'security', rolePrefix: 'security', specialistId: 'cx-security' },
+  'data-analyst': { classifierKey: 'dataAnalyst', rolePrefix: 'data-analyst', specialistId: 'cx-data-analyst' },
+  sre: { classifierKey: 'sre', rolePrefix: 'sre', specialistId: 'cx-sre', baseOnly: true },
+  operations: { classifierKey: 'operations', rolePrefix: 'operations', specialistId: 'cx-operations', baseOnly: true },
+  'release-manager': { classifierKey: 'releaseManager', rolePrefix: 'release-manager', specialistId: 'cx-release-manager', baseOnly: true },
+  'docs-keeper': { classifierKey: 'docsKeeper', rolePrefix: 'docs-keeper', specialistId: 'cx-docs-keeper', baseOnly: true },
+  reviewer: { classifierKey: 'reviewer', rolePrefix: 'reviewer', specialistId: 'cx-reviewer' },
+  'devil-advocate': { classifierKey: 'devilAdvocate', rolePrefix: 'devil-advocate', specialistId: 'cx-devil-advocate', baseOnly: true },
+  evaluator: { classifierKey: 'evaluator', rolePrefix: 'evaluator', specialistId: 'cx-evaluator', baseOnly: true },
+  'trace-reviewer': { classifierKey: 'traceReviewer', rolePrefix: 'trace-reviewer', specialistId: 'cx-trace-reviewer', baseOnly: true },
+  researcher: { classifierKey: 'researcher', rolePrefix: 'researcher', specialistId: 'cx-researcher' },
+  'ux-researcher': { classifierKey: 'uxResearcher', rolePrefix: 'ux-researcher', specialistId: 'cx-ux-researcher', baseOnly: true },
+  explorer: { classifierKey: 'explorer', rolePrefix: 'explorer', specialistId: 'cx-explorer', baseOnly: true },
+  designer: { classifierKey: 'designer', rolePrefix: 'designer', specialistId: 'cx-designer' },
+  accessibility: { classifierKey: 'accessibility', rolePrefix: 'designer.accessibility', specialistId: 'cx-accessibility', baseOnly: true },
+  debugger: { classifierKey: 'debugger', rolePrefix: 'debugger', specialistId: 'cx-debugger', baseOnly: true },
+};
+
+const BY_CLASSIFIER = Object.fromEntries(
+  Object.values(SPECIALIST_FLAVOR_BINDINGS).map((b) => [b.classifierKey, b]),
+);
+
+const BY_SPECIALIST = Object.fromEntries(
+  Object.entries(SPECIALIST_FLAVOR_BINDINGS).map(([name, b]) => [name, b]),
+);
+
+export function bindingForSpecialist(shortName) {
+  return BY_SPECIALIST[shortName] ?? null;
+}
+
+export function bindingForClassifier(classifierKey) {
+  return BY_CLASSIFIER[classifierKey] ?? null;
+}
+
+export function resolveRoleOverlayId(binding, flavor) {
+  if (!binding || !flavor) return null;
+  if (binding.baseOnly || flavor === 'core') return binding.rolePrefix;
+  return `${binding.rolePrefix}.${flavor}`;
+}
+
+export function formatOverlayLine(classifierKey, flavor) {
+  const binding = bindingForClassifier(classifierKey);
+  if (!binding || !flavor) return null;
+  const roleId = resolveRoleOverlayId(binding, flavor);
+  if (!roleId) return null;
+  return `${binding.specialistId}: loaded ${roleId} overlay`;
+}

package/lib/roles/gateway.mjs

@@ -19,6 +19,42 @@ import { route as routeEvent } from './router.mjs';
 import { runBd } from '../beads-client.mjs';
 import { doctorRoot } from '../config/xdg.mjs';
 
+/**
+ * Team escalation support — loads team definitions from specialists/org
+ * and resolves escalation paths when decisions hit forbidden or unresolvable situations.
+ */
+
+function loadTeamRegistry(root) {
+  try {
+    const regPath = join(root, 'specialists', 'teams-registry.json');
+    if (!existsSync(regPath)) return null;
+    return JSON.parse(readFileSync(regPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function findTeamByRoleOwner(roleId, registry) {
+  if (!registry || !Array.isArray(registry.teams)) return null;
+  return registry.teams.find((team) => team.owner === roleId);
+}
+
+export function getTeamEscalationPath(teamId, registry) {
+  if (!registry || !Array.isArray(registry.teams)) return [];
+  const team = registry.teams.find((t) => t.id === teamId);
+  return team?.escalationPath || [];
+}
+
+export function canTeamMakeDecision(teamId, decisionId, registry) {
+  if (!registry || !Array.isArray(registry.teams)) return false;
+  const team = registry.teams.find((t) => t.id === teamId);
+  if (!team) return false;
+  if (Array.isArray(team.forbiddenDecisions) && team.forbiddenDecisions.includes(decisionId)) {
+    return false; // forbidden
+  }
+  return Array.isArray(team.decisionRights) && team.decisionRights.includes(decisionId);
+}
+
 // CONSTRUCT_ROLES_ROOT still wins for the roles event ecosystem's test
 // isolation; the literal fallback follows the global doctor root instead of ~/.cx.
 
@@ -38,8 +74,37 @@ const DEFAULTS = {
 };
 
 function ensureDir() {
-  const r = rootDir();
-  if (!existsSync(r)) mkdirSync(r, { recursive: true });
+   const r = rootDir();
+   if (!existsSync(r)) mkdirSync(r, { recursive: true });
+}
+
+function raisedPath() {
+    return join(rootDir(), 'gateway-raised.jsonl');
+}
+
+function teamsPath() {
+    return join(rootDir(), 'team-decisions.jsonl');
+}
+
+function readRaisedFingerprints() {
+   const rp = raisedPath();
+   if (!existsSync(rp)) return [];
+   try {
+     return readFileSync(rp, 'utf8')
+       .split('\n')
+       .filter(Boolean)
+       .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+       .filter(Boolean);
+   } catch { return []; }
+}
+
+function fingerprintAlreadyRaised(fingerprint) {
+   return readRaisedFingerprints().some((r) => r.fingerprint === fingerprint && r.beadId);
+}
+
+function recordRaisedFingerprint(fingerprint, beadId) {
+   ensureDir();
+   appendFileSync(raisedPath(), JSON.stringify({ fingerprint, beadId, ts: Date.now() }) + '\n');
 }
 
 function readPending() {
@@ -132,32 +197,44 @@ export function shouldEscalate(event, manifest, now = Date.now()) {
 }
 
 async function createBdIncident(event, routeResult) {
-  const labels = (routeResult.manifest.outputs?.bdLabels || []).join(',') || 'incident';
-  const firstLine = String(event.summary || '').split('\n')[0].slice(0, 120);
-  const title = `[${routeResult.personaId}] ${event.type} — ${firstLine}`;
-  const body = JSON.stringify(
-    {
-      eventType: event.type,
-      ts: event.ts,
-      project: event.project,
-      branch: event.branch,
-      cwd: event.cwd,
-      summary: event.summary,
-      context: event.context,
-      fingerprint: event.fingerprint,
-      fence: routeResult.manifest.fence || {},
-      handoffCandidates: routeResult.manifest.handoffCandidates || [],
-    },
-    null,
-    2
-  );
-  const result = await runBd(
-    ['create', title, '-t', 'bug', '-l', labels, '-d', body],
-    { actor: `roles:${routeResult.personaId}`, silent: true, timeoutSeconds: 10, commandTimeoutSeconds: 30 }
-  );
-  if (!result.success) return { success: false, error: result.error || 'bd-failed' };
-  const match = String(result.output || '').match(/Created issue:\s*([\w-]+)/);
-  return { success: true, issueId: match ? match[1] : null, raw: result.output };
+   // Dedup: check if this fingerprint has already been raised as a bead
+   if (fingerprintAlreadyRaised(event.fingerprint)) {
+     return { success: true, skipped: true, reason: 'fingerprint-already-raised', fingerprint: event.fingerprint };
+   }
+
+   const labels = (routeResult.manifest.outputs?.bdLabels || []).join(',') || 'incident';
+   const firstLine = String(event.summary || '').split('\n')[0].slice(0, 120);
+   const title = `[${routeResult.personaId}] ${event.type} — ${firstLine}`;
+   const body = JSON.stringify(
+     {
+       eventType: event.type,
+       ts: event.ts,
+       project: event.project,
+       branch: event.branch,
+       cwd: event.cwd,
+       summary: event.summary,
+       context: event.context,
+       fingerprint: event.fingerprint,
+       fence: routeResult.manifest.fence || {},
+       handoffCandidates: routeResult.manifest.handoffCandidates || [],
+     },
+     null,
+     2
+   );
+   const result = await runBd(
+     ['create', title, '-t', 'bug', '-l', labels, '-d', body],
+     { actor: `roles:${routeResult.personaId}`, silent: true, timeoutSeconds: 10, commandTimeoutSeconds: 30 }
+   );
+   if (!result.success) return { success: false, error: result.error || 'bd-failed' };
+   const match = String(result.output || '').match(/Created issue:\s*([\w-]+)/);
+   const beadId = match ? match[1] : null;
+   
+   // Record this fingerprint as raised
+   if (beadId) {
+     recordRaisedFingerprint(event.fingerprint, beadId);
+   }
+   
+   return { success: true, issueId: beadId, raw: result.output };
 }
 
 async function emitToastBestEffort(payload) {
@@ -339,4 +416,38 @@ export function resetPending() {
   if (existsSync(pp)) writeFileSync(pp, '');
 }
 
-export const _gatewayPaths = { rootDir, pendingPath };
+/**
+ * Record a team decision (approved, blocked, or escalated) for policy-gate
+ * authority checks and durable audit trails.
+ */
+export function recordTeamDecision(decisionId, teamId, outcome = 'pending', context = {}) {
+  ensureDir();
+  const entry = {
+    ts: Date.now(),
+    decisionId,
+    teamId,
+    outcome, // 'approved', 'blocked', 'escalated', 'pending'
+    context,
+  };
+  appendFileSync(teamsPath(), JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+/**
+ * Record a forbidden decision attempt — someone tried to make a decision the team is not allowed to make.
+ */
+export function recordForbiddenDecision(decisionId, teamId, reason = '', context = {}) {
+  ensureDir();
+  const entry = {
+    ts: Date.now(),
+    type: 'forbidden-decision',
+    decisionId,
+    teamId,
+    reason,
+    context,
+  };
+  appendFileSync(teamsPath(), JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+export const _gatewayPaths = { rootDir, pendingPath, teamsPath };

package/lib/roles/manifest.mjs

@@ -1,25 +1,34 @@
 /**
  * lib/roles/manifest.mjs — role manifest loader.
  *
- * Reads specialists/role-manifests.json. A persona is "onboarded" when its
- * `events` array is non-empty. Empty entries reserve the slot for future
- * wiring without code change.
+ * Reads role manifest data from the unified registry (specialists/org).
+ * A persona is "onboarded" when its `events` array is non-empty. Empty entries reserve
+ * the slot for future wiring without code change.
  */
 
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const MANIFEST_PATH = join(__dirname, '..', '..', 'specialists', 'role-manifests.json');
+import { loadRegistry } from '../registry/loader.mjs';
 
 let cached = null;
 
 function load() {
   if (cached) return cached;
-  const raw = readFileSync(MANIFEST_PATH, 'utf8');
-  const parsed = JSON.parse(raw);
-  cached = parsed.personas || {};
+  const registry = loadRegistry();
+  // Extract personas from specialists: map specialist events/fence to persona format
+  const personas = {};
+  for (const [specId, spec] of Object.entries(registry.specialists)) {
+    const personaId = specId.replace(/^cx-/, '');
+    personas[personaId] = {
+      events: spec.events || [],
+      severityImmediate: spec.severityImmediate || [],
+      killSwitchEnv: spec.killSwitchEnv || '',
+      fence: spec.fence || {},
+      handoffCandidates: spec.handoffCandidates || [],
+      outputs: {
+        docTypes: spec.docArtifacts || [],
+      },
+    };
+  }
+  cached = personas;
   return cached;
 }
 
@@ -45,4 +54,4 @@ export function listAllPersonas() {
 
 export function _resetCache() {
   cached = null;
-}
+}

package/lib/roles/router.mjs

@@ -2,7 +2,7 @@
  * lib/roles/router.mjs — pure event → persona resolver.
  *
  * Reads ownership from the declarative routing tables built off of
- * specialists/registry.json, then validates against the loaded role
+ * specialists/org, then validates against the loaded role
  * manifest. Returns null silently when the event has no declared owner
  * or the persona is not yet onboarded — letting ownership be declared
  * ahead of full wiring.

package/lib/scopes/enrich.mjs

@@ -0,0 +1,67 @@
+/**
+ * lib/scopes/enrich.mjs — Attach org teams and roles to an active work scope.
+ *
+ * Scopes (specialists/org/scopes/*.json) carry intake taxonomy, templates, and
+ * tone only. Teams and roles always come from specialists/org — one org, no
+ * per-scope squad forks.
+ */
+
+import { loadRegistry } from '../registry/loader.mjs';
+
+function mapTeam(team) {
+  return {
+    id: team.id,
+    name: team.name || team.id,
+    owner: team.owner,
+    roles: team.roles || [],
+    decisionRights: team.decisionRights || [],
+    forbiddenDecisions: team.forbiddenDecisions || [],
+    escalationPath: team.escalationPath || [],
+    charter: team.charter || '',
+    contact: team.contact || {},
+    specialists: team.specialists || [],
+    groupId: team.groupId || null,
+    kind: team.kind || null,
+  };
+}
+
+export function registryTeamsFromOrg(registry) {
+  return Object.values(registry.teams || {})
+    .filter((team) => team?.id)
+    .map(mapTeam)
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function deriveRegistryRoles(registry) {
+  const roles = new Set();
+  for (const spec of Object.values(registry.specialists || {})) {
+    if (spec?.name) roles.add(spec.name);
+  }
+  return [...roles].sort();
+}
+
+export function enrichScope(raw, { rootDir } = {}) {
+  if (!raw || typeof raw !== 'object') return raw;
+  const scope = { ...raw };
+  const registry = loadRegistry({ rootDir });
+
+  if (!Array.isArray(scope.teams) || scope.teams.length === 0) {
+    scope.teams = registryTeamsFromOrg(registry);
+  }
+
+  if (!Array.isArray(scope.roles) || scope.roles.length === 0) {
+    scope.roles = deriveRegistryRoles(registry);
+  }
+
+  return scope;
+}
+
+export function collectScopeRoleIds(rawScope, { rootDir } = {}) {
+  const enriched = enrichScope(rawScope, { rootDir });
+  const roles = new Set(enriched?.roles || []);
+  for (const team of enriched?.teams || []) {
+    for (const role of team.roles || []) roles.add(role);
+    if (team.owner) roles.add(team.owner);
+  }
+  return roles;
+}

package/lib/scopes/hooks.mjs

@@ -0,0 +1,12 @@
+/**
+ * lib/scopes/hooks.mjs — Scope-level session hook toggles.
+ *
+ * Curated scopes declare hooks.sessionReflect and hooks.sessionOptimize.
+ * Callers consult these before firing optional session-end behaviors.
+ */
+
+export function isScopeHookEnabled(scope, hookName) {
+  const setting = scope?.hooks?.[hookName];
+  if (setting === 'off') return false;
+  return setting === 'on' || setting === undefined;
+}