@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/scopes/lifecycle.mjs

@@ -10,7 +10,11 @@
  *
  * Lifecycle stages:
  *   draft     - in `.cx/scopes/draft-<id>/` with requirements.md + scope.json
- *   active    - in `specialists/org/scopes/<id>.json` (curated) or `.cx/scope.json` (custom)
+ *   active    - in `specialists/org/scopes/<id>.json` (curated), or a named
+ *               custom profile under the construct-rf26.13 config-layer tiers
+ *               (`~/.construct/org/scopes/<id>.json` or
+ *               `<project>/.cx/org/scopes/<id>.json`), or the single-file
+ *               `.cx/scope.json` escape hatch (custom, anonymous)
  *   archived  - in `archive/scopes/<id>/` with the final state and an
  *               archive-note.md explaining why it was retired
  *
@@ -41,23 +45,22 @@ function archiveDir(cwd, id) {
 
 const REQUIREMENTS_BRIEF = (id, displayName) => `# Scope requirements: ${displayName} (${id})
 
-This brief is a discovery and design contract for a new Construct scope. Methodology lives in \`docs/guides/concepts/persona-research.md\` and lifecycle in \`docs/guides/concepts/scope-lifecycle.md\`. Treat each section as a task to dispatch to the named specialist. A draft scope is not ready to promote until every section has evidence backing it. The aim is research-grounded, not opinion-grounded.
+This brief is a discovery and design contract for a new Construct scope. Methodology lives in \`docs/guides/concepts/persona-research.md\` and lifecycle in \`docs/guides/concepts/profile-lifecycle.md\`. Treat each section as a task to dispatch to the named specialist. A draft scope is not ready to promote until every section has evidence backing it. The aim is research-grounded, not opinion-grounded.
 
 Specialists used here are the existing Construct cx-* personas (already in the registry). They are dispatched the standard way; this doc just names which questions each one owns.
 
+A scope selects flows and skill emphasis over the shared, fixed 12-role core roster (\`specialists/org/specialists/\`) — it does not invent new roles or departments. If this org genuinely needs a role absent from that roster, author it as a custom specialist via the construct-rf26.13 config layer (\`construct specialist create <id> --custom\`, docs/guides/cookbook/custom-specialists-and-teams.md) rather than declaring it inline here.
+
 This draft scaffolding produces:
-- \`scope.json\` — the structural definition (departments, roles, intake)
+- \`scope.json\` — the structural definition (intake taxonomy, doc templates, skill emphasis)
 - \`requirements.md\` — this brief
-- \`personas/<role>.md\` — one persona artifact per role (filled during the discover phase)
-- \`departments/<dept>.md\` — one charter doc per department (filled during the frame phase)
-
-The persona and department files start as templates. Filling them from evidence is the actual work; the JSON is just a manifest.
+- \`personas/<role>.md\` — optional, only when \`seedRoles\` names a role genuinely absent from the core roster (rare; most orgs route entirely through the existing 12)
 
-## 1. Discovery (cx-ux-researcher)
+## 1. Discovery (cx-researcher)
 
 Goal: characterize the people, the work, and the outputs of this org type.
 
-- Who are the typical roles in this org? Name 4 to 8 with one-line responsibilities.
+- Which of the 12 core roles (architect, reviewer, engineer, debugger, qa, security, operations, product-manager, data-analyst, designer, researcher, orchestrator) are primary for this org, and which are rarely if ever needed?
 - What is the dominant work loop? Describe in 5 to 8 stages.
 - What are the recurring signals that enter the loop (briefs, bug reports, customer messages, etc.)?
 - What are the canonical output artifacts (campaigns, runbooks, papers, etc.)?
@@ -67,23 +70,23 @@ Goal: characterize the people, the work, and the outputs of this org type.
 
 Goal: turn discovery into an intake taxonomy and a stage sequence.
 
-- Propose intake types (max 24). Each must be: distinct, observable, and routable to a primary owner.
+- Propose intake types (max 24). Each must be: distinct, observable, and routable to a primary owner among the 12 core roles.
 - Propose stages (max 12). Order matters; each stage must answer "what changed?" not just "what happened next?".
-- For each intake type, name the primary owner role and the recommended chain (max 3 hops).
+- For each intake type, name the primary owner role (one of the 12) and the recommended chain (max 3 hops).
 - For each stage, name the dominant artifact produced.
 - Acceptance: a representative real signal classifies into a single intake type with confidence > 0.6.
 
-## 3. Architecture (cx-architect)
+## 3. Skill emphasis (cx-architect)
 
-Goal: define the role set and how it interlocks with the curated cx-* registry.
+Goal: pick the flows and skill bundles this profile should emphasize from the shared registry — not a new role set.
 
-- List role ids the scope will reference (max 80, grouped into max 12 departments with max 20 roles per department). For each, indicate one of:
-  reuse-existing (name the cx-* agent), create-new (specify scope), or compose-overlay (which base role + which flavor).
-- Identify cross-role handoffs. Where can ambiguity stall the loop? Name the orchestrator role.
-- Validate against the per-role cap (max 6 flavors per role per scope).
-- Acceptance: every declared role either exists in specialists/org or has a written scope statement.
+- For each doc template the profile ships, confirm a docTemplates entry exists and name its owning role.
+- List the \`defaultSkills\` (skill ids under \`skills/\`) this org's work loop leans on most — these become the profile's baseline skill entitlement (lib/skills/router.mjs), on top of whatever an individual specialist already carries.
+- Set \`researchProfiles\` per intake type (external, user, codebase, market, compliance) and \`toneDefaults\` per doc template.
+- Name the orchestrator's role in this loop (routing/dispatch is always cx-orchestrator; this just confirms nothing here bypasses it).
+- Acceptance: every \`defaultSkills\` entry resolves to a real file under \`skills/\`; every doc template maps to an owning role among the 12.
 
-## 4. Validation (cx-evaluator)
+## 4. Validation (cx-reviewer)
 
 Goal: prove the draft works on real signals before promotion.
 
@@ -93,13 +96,14 @@ Goal: prove the draft works on real signals before promotion.
 
 ## 5. Promotion (operator decision)
 
-Goal: move the draft into the active catalog.
+Goal: move the draft into the active catalog, or leave it as a durable custom profile.
 
 - Curated path: hand-edit \`specialists/org/scopes/${id}.json\` from this draft, open a PR, run \`npm run lint:scopes\`.
-- Custom path: copy the draft scope.json to \`<project>/.cx/scope.json\` with \`"custom": true\`; \`construct scope set\` for switching between curated.
-- Either path requires the validation acceptance criteria above to be met.
+- Custom path (named, reusable): copy the draft scope.json to \`<project>/.cx/org/scopes/${id}.json\` (project tier, git-tracked) or \`~/.construct/org/scopes/${id}.json\` (user tier, shared across projects) — the same builtin -> user -> project precedence construct-rf26.13 gives custom specialists and teams. Then \`construct scope set ${id}\` switches to it exactly like a curated scope.
+- Custom path (anonymous, one-off): copy the draft scope.json to \`<project>/.cx/scope.json\` with \`"custom": true\` — the pre-rf26.13 escape hatch, still supported for a single ad hoc override.
+- Any path requires the validation acceptance criteria above to be met.
 
-## 6. Health monitoring (cx-evaluator + cx-trace-reviewer)
+## 6. Health monitoring (cx-reviewer)
 
 Goal: keep the scope honest after it ships.
 
@@ -107,7 +111,7 @@ Goal: keep the scope honest after it ships.
 - Any role with success-rate < 0.5 across 10+ runs triggers a review: is the role wrong, the prompt wrong, or the routing wrong?
 - Health data is the input for future scope revisions; never edit a scope without a health report first.
 
-## 7. Archive (cx-docs-keeper + operator)
+## 7. Archive (cx-operations + operator)
 
 Goal: retire a scope cleanly without losing the learning.
 
@@ -397,7 +401,7 @@ export function scopeHealth(cwd, scopeId, { windowDays = 30 } = {}) {
 
   return {
     scope: scopeId,
-    scopeExists: !!loadScope(scopeId),
+    scopeExists: !!loadScope(scopeId, { cwd }),
     windowDays,
     observationCount,
     roles: roleSummary,

package/lib/scopes/loader.mjs

@@ -1,12 +1,23 @@
 /**
  * lib/scopes/loader.mjs — Work-scope loader (intake lens + org enrichment).
  *
- * Curated scopes live in specialists/org/scopes/<id>.json. Custom overrides
- * use <cwd>/.cx/scope.json with custom: true. construct.config.json scope
- * field selects the active scope id (default rnd).
+ * Curated scopes live in specialists/org/scopes/<id>.json. Named custom
+ * scopes reuse the builtin -> user -> project precedence construct-rf26.13
+ * established for specialists/teams (lib/registry/assemble.mjs): an id also
+ * resolves from ~/.construct/org/scopes/<id>.json (shared across every
+ * project on the machine) and <cwd>/.cx/org/scopes/<id>.json (git-tracked,
+ * highest precedence), instead of a scope-specific mechanism. A later tier's
+ * fields shallow-merge over an earlier tier's on id collision.
  *
- * Teams and roles are not authored in scope files — enrich.mjs attaches them
- * from specialists/org at load time.
+ * The single-file <cwd>/.cx/scope.json escape hatch (custom: true) still
+ * works for an anonymous, one-off override — it predates rf26.13 and stays
+ * for the "just this project, no id to remember" case — but a named, reusable
+ * custom profile should live under the tiered org/scopes/ layer so it can be
+ * switched to with `construct scope set <id>` like a curated one.
+ *
+ * construct.config.json's scope field selects the active curated/custom id
+ * (default rnd). Teams and roles are not authored in scope files — enrich.mjs
+ * attaches them from specialists/org at load time.
  */
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
@@ -14,6 +25,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { enrichScope } from './enrich.mjs';
+import { homeDir } from '../paths.mjs';
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(MODULE_DIR, '..', '..');
@@ -21,18 +33,43 @@ const SCOPES_DIR = join(REPO_ROOT, 'specialists', 'org', 'scopes');
 
 export const DEFAULT_SCOPE_ID = 'rnd';
 
-export function loadScope(id, opts = {}) {
-  if (!id || typeof id !== 'string') return null;
-  const path = join(SCOPES_DIR, `${id}.json`);
-  if (!existsSync(path)) return null;
+function userScopesDir() {
+  return join(homeDir(), '.construct', 'org', 'scopes');
+}
+
+function projectScopesDir(cwd) {
+  return join(cwd, '.cx', 'org', 'scopes');
+}
+
+function readScopeTier(dir, id) {
+  const p = join(dir, `${id}.json`);
+  if (!existsSync(p)) return null;
   try {
-    const raw = JSON.parse(readFileSync(path, 'utf8'));
-    return enrichScope(raw, opts);
+    return JSON.parse(readFileSync(p, 'utf8'));
   } catch {
     return null;
   }
 }
 
+function resolveScopeRaw(id, cwd) {
+  const tiers = [SCOPES_DIR, userScopesDir(), projectScopesDir(cwd)];
+  let merged = null;
+  for (const dir of tiers) {
+    const raw = readScopeTier(dir, id);
+    if (!raw) continue;
+    merged = merged ? { ...merged, ...raw } : raw;
+  }
+  return merged;
+}
+
+export function loadScope(id, opts = {}) {
+  if (!id || typeof id !== 'string') return null;
+  const cwd = opts.cwd || process.cwd();
+  const raw = resolveScopeRaw(id, cwd);
+  if (!raw) return null;
+  return enrichScope(raw, opts);
+}
+
 export function listScopes() {
   if (!existsSync(SCOPES_DIR)) return [];
   return readdirSync(SCOPES_DIR)
@@ -64,7 +101,7 @@ export function loadCustomScope(cwd) {
 
 export function resolveActiveScope(cwd, configScopeId = null) {
   const rootDir = REPO_ROOT;
-  const enrichOpts = { rootDir };
+  const enrichOpts = { rootDir, cwd };
   if (configScopeId) {
     const s = loadScope(configScopeId, enrichOpts);
     if (s) return s;

package/lib/scopes/teams.mjs

@@ -10,7 +10,7 @@ const OPERATIONS_OBJECTIVE_RULES = [
   {
     teamId: 'operations-team',
     focus: 'reliability',
-    attachTo: ['cx-sre', 'cx-docs-keeper'],
+    attachTo: ['cx-operations'],
     pattern: /\b(incident|outage|deploy|deployment|rollback|reliability|runbook|postmortem|sre|on-?call)\b/i,
   },
   {

package/lib/security/ingest-boundary.mjs

@@ -0,0 +1,80 @@
+/**
+ * lib/security/ingest-boundary.mjs — Source-kind → trust-level mapping at the
+ * ingest boundary.
+ *
+ * Maps named source kinds (provider type, pipeline stage, ingestion method)
+ * to canonical trust levels and stamps them onto records using the primitives
+ * in lib/security/trust.mjs.
+ *
+ * The module is additive — existing ingest, embed, or storage code is not modified.
+ * Callers that want labeling import `stampIngestBoundary` and
+ * apply it at the point where external content enters Construct's data layer.
+ *
+ * References: CX-AUDIT-LLMSEC-001, construct-9oi4.14.1
+ */
+
+import { TRUST_LEVELS, stampTrust } from './trust.mjs';
+
+// ---------------------------------------------------------------------------
+// Source-kind registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Mapping from well-known source kind strings to trust levels.
+ * All entries are lowercase; callers should normalise before lookup.
+ */
+const SOURCE_KIND_MAP = {
+  // Built-in / internal
+  'builtin-prompt':   TRUST_LEVELS.TRUSTED_INTERNAL,
+  'validated-pack':   TRUST_LEVELS.TRUSTED_INTERNAL,
+
+  // Team-authored local content
+  'team-authored':    TRUST_LEVELS.TEAM_AUTHORED,
+  'local-committed':  TRUST_LEVELS.TEAM_AUTHORED,
+
+  // Authenticated external providers
+  'github-issue':     TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'github-pr':        TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'github-comment':   TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'jira-ticket':      TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'jira-comment':     TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'confluence-page':  TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  'linear-issue':     TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+
+  // Unauthenticated / parsed / scraped content
+  'docling-parsed':   TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  'web-fetched':      TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  'web-search-result': TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  'pdf-extracted':    TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  'unknown':          TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+};
+
+/**
+ * Resolve the trust level for a given source kind string.
+ * Unrecognised kinds default to EXTERNAL_UNAUTHENTICATED (fail-safe).
+ *
+ * @param {string} sourceKind
+ * @returns {string} TRUST_LEVELS value
+ */
+export function resolveTrustLevel(sourceKind) {
+  const key = (sourceKind ?? 'unknown').toLowerCase();
+  return SOURCE_KIND_MAP[key] ?? TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED;
+}
+
+/**
+ * Stamp a trust label onto a record at the ingest boundary.
+ *
+ * Maps `sourceKind` to the appropriate trust level and delegates to
+ * `stampTrust`. The resulting record has a `_trust` field that downstream
+ * consumers (recall wrappers, context assemblers) can inspect.
+ *
+ * @param {Record<string, unknown>} record     The record being ingested.
+ * @param {string}                  sourceKind Well-known source kind string.
+ * @param {{ sourceRef?: string }}  [options]  Optional extra metadata.
+ * @returns {Record<string, unknown>} Stamped record (source record not mutated).
+ */
+export function stampIngestBoundary(record, sourceKind, options = {}) {
+  const level = resolveTrustLevel(sourceKind);
+  const source = options.sourceRef ?? sourceKind ?? 'unknown';
+  return stampTrust(record, level, source);
+}

package/lib/security/recall-wrapper.mjs

@@ -0,0 +1,99 @@
+/**
+ * lib/security/recall-wrapper.mjs — Trust-aware context assembly for recalled
+ * records.
+ *
+ * Before a set of recalled observations or documents is assembled into model
+ * context, callers pass them through `wrapForContextAssembly`. Records
+ * stamped as external (authenticated or unauthenticated) are wrapped with
+ * explicit untrusted delimiters. Internal and team-authored records pass
+ * through unchanged. Unstamped records are warned and treated as the most
+ * restrictive level: EXTERNAL_UNAUTHENTICATED.
+ *
+ * The module is additive — existing memory, recall, or context assembly code is not modified.
+ * Integration is left to follow-on beads (N2, N4).
+ *
+ * References: CX-AUDIT-LLMSEC-001, construct-9oi4.14.1
+ */
+
+import { TRUST_LEVELS, recallTrustGrade, stampTrust, wrapUntrusted } from './trust.mjs';
+
+// Trust levels that require the untrusted-delimiter treatment.
+const UNTRUSTED_LEVELS = new Set([
+  TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+]);
+
+/**
+ * Wrap a single recalled record for safe context assembly.
+ *
+ * - TRUSTED_INTERNAL / TEAM_AUTHORED → returned as-is.
+ * - EXTERNAL_AUTHENTICATED / EXTERNAL_UNAUTHENTICATED → content wrapped with
+ *   `[UNTRUSTED:…]` delimiters in both the `content` field (if present) and
+ *   as a `_wrappedContent` convenience field.
+ * - No `_trust` stamp → warned, treated as EXTERNAL_UNAUTHENTICATED.
+ *
+ * @param {Record<string, unknown>} record  A recalled observation/document.
+ * @param {{ warn?: (msg: string) => void }} [opts]
+ * @returns {Record<string, unknown>} Wrapped or passthrough record.
+ */
+export function wrapRecordForContext(record, opts = {}) {
+  const warn = opts.warn ?? ((msg) => console.warn('[recall-wrapper]', msg));
+  let trustMeta = recallTrustGrade(record);
+
+  if (trustMeta === null) {
+    warn(
+      `Recalled record has no _trust stamp — treating as ${TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED}. ` +
+      `Record keys: ${Object.keys(record ?? {}).join(', ') || '(empty)'}`,
+    );
+    // Re-stamp defensively so downstream consumers always see _trust.
+    const stamped = stampTrust(
+      record,
+      TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+      'unstamped-recall',
+    );
+    trustMeta = stamped._trust;
+    record = stamped;
+  }
+
+  if (!UNTRUSTED_LEVELS.has(trustMeta.level)) {
+    // TRUSTED_INTERNAL or TEAM_AUTHORED — pass through unchanged.
+    return record;
+  }
+
+  // External content: wrap any present content field and attach _wrappedContent.
+  const rawContent = record.content ?? record.text ?? record.body ?? null;
+  const wrapped = rawContent != null
+    ? wrapUntrusted(String(rawContent), trustMeta)
+    : null;
+
+  return {
+    ...record,
+    ...(wrapped != null ? { _wrappedContent: wrapped } : {}),
+  };
+}
+
+/**
+ * Wrap an array of recalled records for safe context assembly.
+ *
+ * Iterates each record through `wrapRecordForContext`. The returned array
+ * preserves original order. Non-object entries are returned as-is with a
+ * warning (defensive).
+ *
+ * @param {unknown[]} records  Array of recalled observations or documents.
+ * @param {{ warn?: (msg: string) => void }} [opts]
+ * @returns {unknown[]} Array of wrapped/passthrough records.
+ */
+export function wrapForContextAssembly(records, opts = {}) {
+  if (!Array.isArray(records)) {
+    throw new TypeError('wrapForContextAssembly: records must be an array');
+  }
+  const warn = opts.warn ?? ((msg) => console.warn('[recall-wrapper]', msg));
+
+  return records.map((record, idx) => {
+    if (record === null || typeof record !== 'object') {
+      warn(`Record at index ${idx} is not an object — skipping wrap (type: ${typeof record})`);
+      return record;
+    }
+    return wrapRecordForContext(record, { warn });
+  });
+}

package/lib/security/trust.mjs

@@ -0,0 +1,132 @@
+/**
+ * lib/security/trust.mjs — Trust taxonomy and stamping primitives.
+ *
+ * Provides a machine-checkable trust hierarchy for all content that flows
+ * through Construct: ingested documents, recalled observations, provider
+ * responses, and built-in prompts. Callers stamp records at ingestion time
+ * and downstream consumers check the stamp before assembling model context.
+ *
+ * Integration into callers (ingest/embed/storage paths) is handled by
+ * follow-on beads (N2, N4). This module is additive — it exports utilities
+ * only; no existing code is modified.
+ *
+ * References: CX-AUDIT-LLMSEC-001, OWASP LLM01 [S12][S13], construct-9oi4.14.1
+ */
+
+// ---------------------------------------------------------------------------
+// Trust level taxonomy (ordered lowest → highest trust)
+// ---------------------------------------------------------------------------
+
+/** @type {Record<string, string>} */
+export const TRUST_LEVELS = {
+  /** Scraped or parsed content with no authorship verification (web pages,
+   *  docling-extracted text, unknown origin). Highest risk of injection. */
+  EXTERNAL_UNAUTHENTICATED: 'external-unauthenticated',
+
+  /** Content from an authenticated external actor: a known GitHub user's
+   *  issue-tracker comment, a named Jira reporter, a Confluence page with
+   *  attributed authorship. Lower risk but still untrusted. */
+  EXTERNAL_AUTHENTICATED: 'external-authenticated',
+
+  /** Authored by a member of the Construct team or project (e.g. a local
+   *  markdown file committed by the team). Trusted but not built-in. */
+  TEAM_AUTHORED: 'team-authored',
+
+  /** Built-in prompts, validated skill packs, and internal system content.
+   *  Full trust — assembled directly into the instruction channel. */
+  TRUSTED_INTERNAL: 'trusted-internal',
+};
+
+// Ordered list for comparison (index = rank, higher index = higher trust).
+const LEVEL_ORDER = [
+  TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED,
+  TRUST_LEVELS.EXTERNAL_AUTHENTICATED,
+  TRUST_LEVELS.TEAM_AUTHORED,
+  TRUST_LEVELS.TRUSTED_INTERNAL,
+];
+
+// ---------------------------------------------------------------------------
+// Stamping
+// ---------------------------------------------------------------------------
+
+/**
+ * Stamp a trust label onto an observation or record object.
+ *
+ * @param {Record<string, unknown>} record  Source object (not mutated).
+ * @param {string}                  level   One of TRUST_LEVELS values.
+ * @param {string}                  source  Human-readable source descriptor.
+ * @returns {Record<string, unknown>} New object with `_trust` metadata added.
+ */
+export function stampTrust(record, level, source) {
+  if (!Object.values(TRUST_LEVELS).includes(level)) {
+    throw new TypeError(
+      `stampTrust: unknown trust level "${level}". ` +
+      `Valid values: ${Object.values(TRUST_LEVELS).join(', ')}`,
+    );
+  }
+  return {
+    ...record,
+    _trust: {
+      level,
+      source: String(source ?? 'unknown'),
+      stampedAt: Date.now(),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Level comparison
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true if `level` meets or exceeds `required` in the trust hierarchy.
+ *
+ * @param {string} level    The trust level of the content being checked.
+ * @param {string} required The minimum acceptable trust level.
+ * @returns {boolean}
+ */
+export function meetsMinTrustLevel(level, required) {
+  const levelIdx = LEVEL_ORDER.indexOf(level);
+  const requiredIdx = LEVEL_ORDER.indexOf(required);
+  if (levelIdx === -1 || requiredIdx === -1) return false;
+  return levelIdx >= requiredIdx;
+}
+
+// ---------------------------------------------------------------------------
+// Context assembly helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap external content with explicit untrusted delimiters so the model
+ * context assembler can visually and programmatically distinguish data from
+ * instructions.
+ *
+ * @param {string}                              content   Raw text content.
+ * @param {{ level: string, source: string }}   trustMeta Trust metadata.
+ * @returns {string} Delimited content string.
+ */
+export function wrapUntrusted(content, trustMeta) {
+  const level = trustMeta?.level ?? TRUST_LEVELS.EXTERNAL_UNAUTHENTICATED;
+  const source = trustMeta?.source ?? 'unknown';
+  return `[UNTRUSTED:${level}:${source}]\n${content}\n[/UNTRUSTED]`;
+}
+
+// ---------------------------------------------------------------------------
+// Recall re-grading
+// ---------------------------------------------------------------------------
+
+/**
+ * Re-grade a recalled record — returns the `_trust` meta object if present,
+ * or null if the record was stored without a trust stamp.
+ *
+ * Callers should treat a null return as EXTERNAL_UNAUTHENTICATED per policy.
+ *
+ * @param {Record<string, unknown>} record A recalled observation or document.
+ * @returns {{ level: string, source: string, stampedAt: number } | null}
+ */
+export function recallTrustGrade(record) {
+  if (record && typeof record._trust === 'object' && record._trust !== null) {
+    return record._trust;
+  }
+  return null;
+}