@thebackstoryis/engineering-with-ai 0.2.9

package/src/team-hub-resources.mjs

@@ -0,0 +1,239 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, relative, resolve } from 'node:path';
+import { TextDecoder } from 'node:util';
+import { z } from 'zod';
+import YAML from 'yaml';
+import { parseOrganisationBlueprintPack } from './organisation-blueprints.mjs';
+import { parseDesignSystemPack } from './design-systems.mjs';
+
+export const TEAM_HUB_RESOURCE_LIMITS = Object.freeze({
+  maximumFiles: 100,
+  maximumFileBytes: 256 * 1024,
+  maximumTotalBytes: 2 * 1024 * 1024,
+  maximumPackageBytes: (2 * 1024 * 1024) + (512 * 1024),
+});
+
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const resourceId = z.string().regex(/^org\.[a-z0-9]+(?:-[a-z0-9]+)*\.[a-z0-9]+(?:[.-][a-z0-9]+)*$/);
+const semanticVersion = z.string().regex(/^\d+\.\d+\.\d+$/);
+const safeExtensions = new Set(['.md', '.yaml', '.yml', '.json', '.txt', '.toml', '.css']);
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+
+const fileSchema = z.object({
+  path: z.string().min(1).max(240),
+  size: z.number().int().min(0).max(TEAM_HUB_RESOURCE_LIMITS.maximumFileBytes),
+  digest,
+  content: z.string(),
+}).strict();
+
+const packageSchema = z.object({
+  schema: z.literal('ewai.team-hub-resource-package/v1'),
+  resource: z.object({
+    kind: z.enum(['organisation-blueprint', 'design-system']),
+    id: resourceId,
+    name: z.string().min(1).max(160),
+    description: z.string().max(1_000),
+    version: semanticVersion,
+    publisher: z.object({
+      id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+      name: z.string().min(1).max(160),
+    }).strict(),
+    compatibility: z.object({ ewai: z.string().regex(/^\d+\.x$/) }).strict(),
+  }).strict(),
+  files: z.array(fileSchema).min(1).max(TEAM_HUB_RESOURCE_LIMITS.maximumFiles),
+  digest,
+}).strict();
+
+function resourceError(message, code = 'invalid-resource-package', status = 400) {
+  return Object.assign(new Error(message), { code, status });
+}
+
+function fileDigest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function normalizedPackage(value) {
+  return {
+    schema: value.schema,
+    resource: value.resource,
+    files: [...value.files]
+      .sort((left, right) => left.path.localeCompare(right.path))
+      .map(({ path, size, digest: itemDigest, content }) => ({ path, size, digest: itemDigest, content })),
+  };
+}
+
+export function teamHubResourcePackageDigest(value) {
+  return `sha256:${createHash('sha256').update(JSON.stringify(normalizedPackage(value))).digest('hex')}`;
+}
+
+function safeResourcePath(value) {
+  const path = String(value ?? '').replaceAll('\\', '/');
+  const segments = path.split('/');
+  if (!path || path.length > 240 || isAbsolute(path) || segments.some((segment) => !segment || segment === '..' || segment.startsWith('.'))) {
+    throw resourceError(`Resource file path is not safe: ${value}`, 'unsafe-resource-path');
+  }
+  if (/[^\t\n\r\x20-\x7e]/.test(path) || !safeExtensions.has(extname(path).toLowerCase())) {
+    throw resourceError(`Resource file type or path is not supported: ${value}`, 'unsupported-resource-file');
+  }
+  return path;
+}
+
+function readPackFile(root, source) {
+  const safePath = safeResourcePath(source);
+  const candidate = resolve(root, safePath);
+  const boundary = relative(root, candidate);
+  if (boundary.startsWith('..') || isAbsolute(boundary)) throw resourceError(`Resource file escapes the pack root: ${safePath}`, 'unsafe-resource-path');
+  if (!existsSync(candidate)) throw resourceError(`Resource file does not exist: ${safePath}`, 'missing-resource-file');
+  if (lstatSync(candidate).isSymbolicLink()) throw resourceError(`Resource files may not be symbolic links: ${safePath}`, 'unsafe-resource-symlink');
+  if (!statSync(candidate).isFile()) throw resourceError(`Resource path must be a file: ${safePath}`, 'invalid-resource-file');
+  const realRoot = realpathSync(root);
+  const realCandidate = realpathSync(candidate);
+  const realBoundary = relative(realRoot, realCandidate);
+  if (realBoundary.startsWith('..') || isAbsolute(realBoundary)) throw resourceError(`Resource file escapes the pack root: ${safePath}`, 'unsafe-resource-path');
+  const bytes = readFileSync(realCandidate);
+  if (bytes.length > TEAM_HUB_RESOURCE_LIMITS.maximumFileBytes) throw resourceError(`Resource file exceeds 256 KiB: ${safePath}`, 'resource-file-too-large');
+  let content;
+  try { content = textDecoder.decode(bytes); }
+  catch { throw resourceError(`Resource file must contain valid UTF-8 text: ${safePath}`, 'invalid-resource-text'); }
+  if (content.includes('\0')) throw resourceError(`Resource file contains binary NUL content: ${safePath}`, 'invalid-resource-text');
+  return { path: safePath, size: bytes.length, digest: fileDigest(bytes), content };
+}
+
+function referencedPaths(pack) {
+  if (pack.type === 'organisation') {
+    return pack.blueprint.modules.flatMap((module) => [
+      ...module.standards.map(({ source }) => source),
+      ...module.personas.map(({ source }) => source),
+      ...module.policies.map(({ source }) => source),
+    ]);
+  }
+  return pack.design_system.contributions.map(({ source }) => source);
+}
+
+function validateManifestBinding(value) {
+  const manifestFile = value.files.find(({ path }) => path === 'pack.yaml');
+  let manifest;
+  try { manifest = YAML.parse(manifestFile?.content ?? ''); }
+  catch { throw resourceError('Resource pack.yaml must contain valid YAML.', 'invalid-resource-manifest'); }
+  if (!manifest || manifest.schema !== 'ewai.pack/v1') throw resourceError('Resource pack.yaml must use ewai.pack/v1.', 'invalid-resource-manifest');
+  const expectedKind = manifest.type === 'organisation' ? 'organisation-blueprint' : manifest.type === 'design-system' ? 'design-system' : null;
+  if (!expectedKind || expectedKind !== value.resource.kind) throw resourceError('Resource kind disagrees with pack.yaml.', 'resource-manifest-mismatch');
+  for (const [field, expected] of [['id', manifest.id], ['name', manifest.name], ['version', manifest.version]]) {
+    if (value.resource[field] !== expected) throw resourceError(`Resource ${field} disagrees with pack.yaml.`, 'resource-manifest-mismatch');
+  }
+  if (value.resource.description !== String(manifest.description ?? '')) throw resourceError('Resource description disagrees with pack.yaml.', 'resource-manifest-mismatch');
+
+  const definition = manifest.type === 'organisation' ? manifest.blueprint : manifest.design_system;
+  if (!definition || value.resource.compatibility.ewai !== definition.compatibility?.ewai) {
+    throw resourceError('Resource compatibility disagrees with pack.yaml.', 'resource-manifest-mismatch');
+  }
+  const expectedPublisherId = manifest.type === 'organisation' ? definition.publisher?.id : String(manifest.id ?? '').split('.')[1];
+  if (value.resource.publisher.id !== expectedPublisherId) throw resourceError('Resource publisher disagrees with pack.yaml.', 'resource-manifest-mismatch');
+  if (manifest.type === 'organisation' && value.resource.publisher.name !== definition.publisher?.name) {
+    throw resourceError('Resource publisher name disagrees with pack.yaml.', 'resource-manifest-mismatch');
+  }
+
+  const references = manifest.type === 'organisation'
+    ? (definition.modules ?? []).flatMap((module) => [
+      ...(module.standards ?? []).map(({ source }) => source),
+      ...(module.personas ?? []).map(({ source }) => source),
+      ...(module.policies ?? []).map(({ source }) => source),
+    ])
+    : (definition.contributions ?? []).map(({ source }) => source);
+  const expectedPaths = [...new Set(['pack.yaml', ...references.map(safeResourcePath)])].sort();
+  const actualPaths = value.files.map(({ path }) => path).sort();
+  if (JSON.stringify(expectedPaths) !== JSON.stringify(actualPaths)) {
+    throw resourceError('Resource file set disagrees with the files referenced by pack.yaml.', 'resource-manifest-mismatch');
+  }
+}
+
+export function buildTeamHubResourcePackage(folder, options = {}) {
+  const root = resolve(String(folder ?? ''));
+  if (!String(folder ?? '').trim() || !existsSync(root) || !statSync(root).isDirectory()) {
+    throw resourceError('Resource publication requires an existing pack folder.', 'invalid-resource-folder');
+  }
+  if (lstatSync(root).isSymbolicLink()) throw resourceError('Resource pack folder must not be a symbolic link.', 'unsafe-resource-symlink');
+  const manifestPath = resolve(root, 'pack.yaml');
+  if (!existsSync(manifestPath) || basename(manifestPath) !== 'pack.yaml') throw resourceError('Resource pack requires pack.yaml.', 'missing-resource-manifest');
+
+  const organisation = parseOrganisationBlueprintPack(manifestPath, 'team-hub-candidate', {
+    limits: { manifestBytes: TEAM_HUB_RESOURCE_LIMITS.maximumFileBytes, itemBytes: TEAM_HUB_RESOURCE_LIMITS.maximumFileBytes, totalBytes: TEAM_HUB_RESOURCE_LIMITS.maximumTotalBytes },
+  });
+  const pack = organisation ?? parseDesignSystemPack(manifestPath, 'team-hub-candidate', {
+    limits: { manifestBytes: TEAM_HUB_RESOURCE_LIMITS.maximumFileBytes, itemBytes: TEAM_HUB_RESOURCE_LIMITS.maximumFileBytes, totalBytes: TEAM_HUB_RESOURCE_LIMITS.maximumTotalBytes, maximumFiles: TEAM_HUB_RESOURCE_LIMITS.maximumFiles },
+  });
+  if (!pack) throw resourceError('Team Hub supports only organisation Blueprint and design-system packs.', 'unsupported-resource-kind');
+  if (!pack.id.startsWith('org.')) throw resourceError('Team Hub resources must use an organisation-owned org.* ID.', 'unsupported-resource-id');
+
+  const publisherId = pack.type === 'organisation' ? pack.blueprint.publisher.id : pack.id.split('.')[1];
+  const publisherName = pack.type === 'organisation'
+    ? pack.blueprint.publisher.name
+    : String(options.publisherName ?? '').trim();
+  if (!publisherName) throw resourceError('Design-system publication requires a publisher name.', 'missing-publisher-name');
+  const compatibility = pack.type === 'organisation' ? pack.blueprint.compatibility : pack.design_system.compatibility;
+  const paths = [...new Set(['pack.yaml', ...referencedPaths(pack)])].sort();
+  const files = paths.map((path) => readPackFile(root, path));
+  const total = files.reduce((sum, file) => sum + file.size, 0);
+  if (files.length > TEAM_HUB_RESOURCE_LIMITS.maximumFiles) throw resourceError('Resource package exceeds 100 files.', 'resource-file-limit');
+  if (total > TEAM_HUB_RESOURCE_LIMITS.maximumTotalBytes) throw resourceError('Resource package exceeds 2 MiB.', 'resource-package-too-large');
+
+  const value = {
+    schema: 'ewai.team-hub-resource-package/v1',
+    resource: {
+      kind: pack.type === 'organisation' ? 'organisation-blueprint' : 'design-system',
+      id: pack.id,
+      name: pack.name,
+      description: pack.description ?? '',
+      version: pack.version,
+      publisher: { id: publisherId, name: publisherName },
+      compatibility: { ...compatibility },
+    },
+    files,
+    digest: `sha256:${'0'.repeat(64)}`,
+  };
+  value.digest = teamHubResourcePackageDigest(value);
+  return validateTeamHubResourcePackage(value);
+}
+
+export function validateTeamHubResourcePackage(input) {
+  let value;
+  try { value = packageSchema.parse(input); }
+  catch (error) {
+    const details = error.issues?.map((issue) => `${issue.path.join('.') || 'package'} ${issue.message}`).join('; ') ?? error.message;
+    throw resourceError(`Team Hub resource package is invalid: ${details}`);
+  }
+  if (value.resource.id.split('.')[1] !== value.resource.publisher.id) {
+    throw resourceError('Resource publisher ID must match the organisation segment in the resource ID.', 'publisher-mismatch');
+  }
+  const seen = new Set();
+  let total = 0;
+  for (const file of value.files) {
+    const path = safeResourcePath(file.path);
+    if (seen.has(path)) throw resourceError(`Resource package repeats a file path: ${path}`, 'duplicate-resource-file');
+    seen.add(path);
+    let bytes;
+    try { bytes = Buffer.from(file.content, 'utf8'); textDecoder.decode(bytes); }
+    catch { throw resourceError(`Resource file must contain valid UTF-8 text: ${path}`, 'invalid-resource-text'); }
+    if (bytes.length !== file.size) throw resourceError(`Resource file size disagrees with its content: ${path}`, 'resource-size-mismatch');
+    if (fileDigest(bytes) !== file.digest) throw resourceError(`Resource file digest disagrees with its content: ${path}`, 'resource-digest-mismatch');
+    total += bytes.length;
+  }
+  if (!seen.has('pack.yaml')) throw resourceError('Resource package must contain pack.yaml.', 'missing-resource-manifest');
+  if (total > TEAM_HUB_RESOURCE_LIMITS.maximumTotalBytes) throw resourceError('Resource package exceeds 2 MiB.', 'resource-package-too-large');
+  validateManifestBinding(value);
+  const expected = teamHubResourcePackageDigest(value);
+  if (value.digest !== expected) throw resourceError('Resource package digest disagrees with its content.', 'resource-package-digest-mismatch');
+  return { ...value, files: [...value.files].sort((left, right) => left.path.localeCompare(right.path)) };
+}
+
+export function projectTeamHubResourceRelease(value) {
+  const pack = validateTeamHubResourcePackage(value);
+  return {
+    schema: 'ewai.team-hub-resource-release/v1',
+    ...pack.resource,
+    digest: pack.digest,
+    fileCount: pack.files.length,
+    totalBytes: pack.files.reduce((sum, file) => sum + file.size, 0),
+  };
+}

package/src/team-hub.mjs

@@ -0,0 +1,242 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import { loadProjectConfig } from './project.mjs';
+
+const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+const packageVersion = JSON.parse(readFileSync(resolve(moduleDirectory, '../package.json'), 'utf8')).version;
+
+export const TEAM_HUB_SNAPSHOT_SCHEMA = 'ewai.team-hub-snapshot/v1';
+export const TEAM_HUB_ENVELOPE_SCHEMA = 'ewai.team-hub-envelope/v1';
+export const TEAM_HUB_RECEIPT_SCHEMA = 'ewai.team-hub-receipt/v1';
+export const TEAM_HUB_DISCLOSURE_SCHEMA = 'ewai.team-hub-disclosure/v1';
+export const TEAM_HUB_AUTHORITY_NOTICE = 'Team Hub is an operational evidence projection. It cannot approve Build or Manual QA, accept risk, certify compliance, deploy or release.';
+
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/, 'must be a sha256 digest');
+const isoDateTime = z.string().datetime({ offset: true });
+const slug = z.string().min(1).max(120).regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/, 'must be a lower-case safe identifier');
+const unsafeReference = /(?:\0|https?:\/\/|file:\/\/|(?:^|\s)\/(?:Users|home|private|tmp|var|etc)\/|[A-Za-z]:\\)/i;
+const safeText = (maximum, label) => z.string().trim().min(1).max(maximum).refine(
+  (value) => !unsafeReference.test(value),
+  `${label} contains an unsafe path or remote reference`,
+);
+const attentionSchema = z.object({
+  code: slug,
+  severity: z.enum(['info', 'warning', 'blocking']),
+  summary: safeText(240, 'attention summary'),
+}).strict();
+const resourceSchema = z.object({
+  kind: z.enum(['organisation-blueprint', 'design-system', 'technology-pack', 'starter-pack']),
+  id: z.string().min(1).max(180).regex(/^(?:ewai|org)\.[a-z0-9.-]+$/),
+  version: z.string().min(1).max(40).regex(/^\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9.-]+)?$/),
+  digest,
+}).strict();
+const intentCountsSchema = z.object({
+  total: z.number().int().min(0).max(100_000),
+  draft: z.number().int().min(0).max(100_000),
+  ready: z.number().int().min(0).max(100_000),
+  inProgress: z.number().int().min(0).max(100_000),
+  completed: z.number().int().min(0).max(100_000),
+  blocked: z.number().int().min(0).max(100_000),
+}).strict().superRefine((value, context) => {
+  const classified = value.draft + value.ready + value.inProgress + value.completed + value.blocked;
+  if (classified !== value.total) context.addIssue({ code: 'custom', message: 'Intent counts must add up to total.' });
+});
+const deliverySchema = z.object({
+  slug,
+  title: safeText(200, 'delivery title'),
+  status: safeText(80, 'delivery status'),
+  currentPhase: safeText(80, 'delivery phase'),
+  updatedAt: isoDateTime,
+  buildApproved: z.boolean(),
+  manualQa: safeText(80, 'Manual QA status'),
+  attention: z.array(attentionSchema).max(20),
+}).strict();
+const snapshotSchema = z.object({
+  schema: z.literal(TEAM_HUB_SNAPSHOT_SCHEMA),
+  project: z.object({ id: slug, name: safeText(200, 'project name') }).strict(),
+  generatedAt: isoDateTime,
+  ewaiVersion: z.string().regex(/^\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9.-]+)?$/).max(40),
+  revision: z.object({ digest }).strict(),
+  intents: intentCountsSchema,
+  delivery: deliverySchema.nullable(),
+  resources: z.array(resourceSchema).max(25),
+  authorityNotice: z.literal(TEAM_HUB_AUTHORITY_NOTICE),
+}).strict();
+const envelopeSchema = z.object({
+  schema: z.literal(TEAM_HUB_ENVELOPE_SCHEMA),
+  idempotencyKey: digest,
+  snapshotDigest: digest,
+  snapshot: snapshotSchema,
+}).strict();
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  return value;
+}
+
+export function teamHubDigest(value) {
+  return `sha256:${createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex')}`;
+}
+
+function parse(schema, value, label) {
+  const result = schema.safeParse(value);
+  if (result.success) return result.data;
+  const detail = result.error.issues.map((issue) => `${issue.path.join('.') || label}: ${issue.message}`).join('; ');
+  throw new Error(`${label} is invalid or contains an unrecognised field: ${detail}`);
+}
+
+export function validateTeamHubSnapshot(value) {
+  return parse(snapshotSchema, value, 'Team Hub snapshot');
+}
+
+export function validateTeamHubReceipt(value) {
+  return parse(z.object({
+    schema: z.literal(TEAM_HUB_RECEIPT_SCHEMA),
+    receiptId: z.string().regex(/^receipt-[a-zA-Z0-9-]{1,100}$/),
+    projectId: slug,
+    snapshotDigest: digest,
+    idempotencyKey: digest,
+    acceptedAt: isoDateTime,
+    replayed: z.boolean(),
+  }).strict(), value, 'Team Hub receipt');
+}
+
+export function buildTeamHubEnvelope(snapshotInput) {
+  const snapshot = validateTeamHubSnapshot(snapshotInput);
+  const snapshotDigest = teamHubDigest(snapshot);
+  return { schema: TEAM_HUB_ENVELOPE_SCHEMA, idempotencyKey: snapshotDigest, snapshotDigest, snapshot };
+}
+
+export function validateTeamHubEnvelope(value) {
+  const envelope = parse(envelopeSchema, value, 'Team Hub envelope');
+  const actual = teamHubDigest(envelope.snapshot);
+  if (envelope.snapshotDigest !== actual || envelope.idempotencyKey !== actual) {
+    throw new Error('Team Hub envelope digest or idempotency key disagrees with its snapshot.');
+  }
+  return envelope;
+}
+
+const disclosureFields = Object.freeze([
+  'project.id', 'project.name', 'generatedAt', 'ewaiVersion', 'revision.digest', 'intents',
+  'delivery', 'resources.kind', 'resources.id', 'resources.version', 'resources.digest', 'authorityNotice',
+]);
+const excludedCategories = Object.freeze([
+  'credentials', 'error-report-packages', 'local-paths', 'logs', 'persona-bodies', 'prompts-and-transcripts',
+  'repository-remotes', 'source-and-specs-bodies',
+]);
+
+export function inspectTeamHubDisclosure() {
+  const contract = { schema: TEAM_HUB_SNAPSHOT_SCHEMA, fields: [...disclosureFields], excluded: [...excludedCategories] };
+  return {
+    schema: TEAM_HUB_DISCLOSURE_SCHEMA,
+    title: 'Exact project snapshot disclosure',
+    fields: contract.fields,
+    excluded: contract.excluded,
+    contractDigest: teamHubDigest(contract),
+    authorityNotice: TEAM_HUB_AUTHORITY_NOTICE,
+  };
+}
+
+function filesUnder(root, suffix, maximum = 10_000) {
+  if (!existsSync(root) || lstatSync(root).isSymbolicLink()) return [];
+  const found = [];
+  const queue = [root];
+  while (queue.length && found.length < maximum) {
+    const current = queue.shift();
+    for (const entry of readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+      if (entry.isSymbolicLink()) continue;
+      const path = resolve(current, entry.name);
+      if (entry.isDirectory()) queue.push(path);
+      if (entry.isFile() && entry.name.endsWith(suffix) && statSync(path).size <= 512 * 1024) found.push(path);
+    }
+  }
+  return found;
+}
+
+function intentCounts(specsRoot) {
+  const counts = { total: 0, draft: 0, ready: 0, inProgress: 0, completed: 0, blocked: 0 };
+  for (const path of filesUnder(resolve(specsRoot, '2.Purpose/intents'), '.json')) {
+    try {
+      const value = JSON.parse(readFileSync(path, 'utf8'));
+      if (value.schema !== 'ewai.intent-state/v1') continue;
+      counts.total += 1;
+      const status = String(value.status ?? '').toLowerCase();
+      if (status === 'completed' || status === 'done') counts.completed += 1;
+      else if (status === 'blocked') counts.blocked += 1;
+      else if (status === 'in-progress' || status === 'in_progress' || value.deliveryStatus === 'in-progress') counts.inProgress += 1;
+      else if (status === 'ready' || status === 'approved') counts.ready += 1;
+      else counts.draft += 1;
+    } catch {
+      // Invalid intent state is not promoted into a Hub snapshot.
+    }
+  }
+  return counts;
+}
+
+function latestDelivery(specsRoot) {
+  const records = [];
+  for (const path of filesUnder(resolve(specsRoot, '6.Build'), 'delivery-state.json', 500)) {
+    try {
+      const state = JSON.parse(readFileSync(path, 'utf8'));
+      if (state.schema !== 'ewai.delivery-state/v1' || !state.updatedAt) continue;
+      const manualQa = (state.humanGates ?? []).find((gate) => gate.id === 'manual-qa');
+      const attention = [];
+      if (state.blockedReason || state.status === 'blocked') attention.push({ code: 'delivery-blocked', severity: 'blocking', summary: 'The latest delivery reports a blocker.' });
+      if ((manualQa?.status ?? 'pending') !== 'approved') attention.push({ code: 'manual-qa-pending', severity: 'info', summary: 'Manual QA remains pending.' });
+      records.push({
+        slug: String(state.slug ?? '').slice(0, 120),
+        title: String(state.intent?.title ?? state.slug ?? 'Delivery').slice(0, 200),
+        status: String(state.status ?? 'unknown').slice(0, 80),
+        currentPhase: String(state.currentPhase ?? 'unknown').slice(0, 80),
+        updatedAt: String(state.updatedAt), buildApproved: Boolean(state.approvals?.build),
+        manualQa: String(manualQa?.status ?? 'pending').slice(0, 80), attention,
+      });
+    } catch {
+      // Invalid delivery state is not promoted into a Hub snapshot.
+    }
+  }
+  return records.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0] ?? null;
+}
+
+function repositoryRevision(projectRoot) {
+  try {
+    const head = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: projectRoot, encoding: 'utf8', timeout: 2_000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    return teamHubDigest({ head });
+  } catch {
+    return teamHubDigest({ head: 'unavailable' });
+  }
+}
+
+function selectedResources(config) {
+  const resources = [];
+  const blueprint = config.blueprints?.organisation?.root;
+  if (blueprint?.id && blueprint?.version && blueprint?.digest) resources.push({ kind: 'organisation-blueprint', id: blueprint.id, version: blueprint.version, digest: blueprint.digest });
+  const design = config.design_system?.root;
+  const designDigest = config.design_system?.effective_digest ?? design?.digest;
+  if (design?.id && design?.version && designDigest) resources.push({ kind: 'design-system', id: design.id, version: design.version, digest: designDigest });
+  return resources.slice(0, 25);
+}
+
+export function buildTeamHubSnapshot(projectRoot, options = {}) {
+  const { config, paths } = loadProjectConfig(projectRoot);
+  const snapshot = {
+    schema: TEAM_HUB_SNAPSHOT_SCHEMA,
+    project: {
+      id: options.projectId ?? 'local-project',
+      name: config.project?.name ?? 'EWAI project',
+    },
+    generatedAt: options.generatedAt ?? new Date().toISOString(),
+    ewaiVersion: packageVersion,
+    revision: { digest: options.revisionDigest ?? repositoryRevision(paths.projectRoot) },
+    intents: options.intents ?? intentCounts(paths.specsRoot),
+    delivery: options.delivery === undefined ? latestDelivery(paths.specsRoot) : options.delivery,
+    resources: options.resources ?? selectedResources(config),
+    authorityNotice: TEAM_HUB_AUTHORITY_NOTICE,
+  };
+  return validateTeamHubSnapshot(snapshot);
+}