@juangcarmona/lighthouse-sdlc 0.3.0 → 0.5.0

package/src/capabilities.mjs

@@ -0,0 +1,84 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+const capabilityAdapters = Object.freeze({
+  'labels/github': 'github-labels',
+});
+
+export function capabilityAdapter(capability) {
+  return capabilityAdapters[`${capability?.id ?? ''}/${capability?.provider ?? ''}`] ?? null;
+}
+
+export function initialAdoptionStatus(capability) {
+  return capability?.selection === 'opt-in' ? 'available' : 'pending-adoption';
+}
+
+export async function readCapabilityCatalog(path = resolve(packageRoot, 'capabilities.json')) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+export function validateCapabilityCatalog(catalog) {
+  const errors = [];
+  if (!isRecord(catalog)) return [issue('catalog.invalid', 'capability catalog must be an object')];
+  if (catalog.schemaVersion !== 1) errors.push(issue('catalog.schema-version', 'catalog schemaVersion must be 1', 'schemaVersion'));
+  if (catalog.package?.name !== '@juangcarmona/lighthouse-sdlc') errors.push(issue('catalog.package', 'catalog package name is incorrect', 'package.name'));
+  if (typeof catalog.package?.version !== 'string' || !/^\d+\.\d+\.\d+$/.test(catalog.package.version)) errors.push(issue('catalog.package-version', 'catalog package version must be semver-like', 'package.version'));
+  if (!Array.isArray(catalog.capabilities) || catalog.capabilities.length === 0) return [...errors, issue('catalog.capabilities', 'catalog capabilities must be a non-empty array', 'capabilities')];
+  const ids = new Set();
+  for (const capability of catalog.capabilities) {
+    if (!isRecord(capability) || typeof capability.id !== 'string' || !capability.id.trim()) {
+      errors.push(issue('catalog.capability', 'every catalog capability needs an id', 'capabilities'));
+      continue;
+    }
+    if (ids.has(capability.id)) errors.push(issue('catalog.duplicate', `catalog capability ${capability.id} appears more than once`, 'capabilities'));
+    ids.add(capability.id);
+    if (typeof capability.provider !== 'string' || !capability.provider) errors.push(issue('catalog.provider', `catalog capability ${capability.id} needs a provider`, 'capabilities'));
+    if (typeof capability.version !== 'string' || !capability.version) errors.push(issue('catalog.version', `catalog capability ${capability.id} needs a version`, 'capabilities'));
+    if (typeof capability.adapter !== 'string' || !capability.adapter) errors.push(issue('catalog.adapter', `catalog capability ${capability.id} needs an adapter`, 'capabilities'));
+    else if (capability.adapter !== capabilityAdapter(capability)) errors.push(issue('catalog.adapter-unsupported', `catalog capability ${capability.id} does not have a registered ${capability.adapter} adapter`, 'capabilities'));
+    if (!isRecord(capability.configuration)) errors.push(issue('catalog.configuration', `catalog capability ${capability.id} needs a configuration object`, 'capabilities'));
+    if (capability.adapter === 'github-labels' && (!Array.isArray(capability.configuration?.labels) || !Array.isArray(capability.configuration?.transitions))) {
+      errors.push(issue('catalog.configuration', `catalog capability ${capability.id} needs labels and transitions for the github-labels adapter`, 'capabilities'));
+    }
+    if (!isRecord(capability.operations) || !Array.isArray(capability.operations.allowed) || !Array.isArray(capability.operations.blocked)) errors.push(issue('catalog.operations', `catalog capability ${capability.id} needs operation policy`, 'capabilities'));
+    else {
+      const allowed = new Set(capability.operations.allowed);
+      const blocked = new Set(capability.operations.blocked);
+      const operationKinds = new Set(['create', 'preserve', 'modify', 'rename', 'remove', 'ambiguous', 'unsupported']);
+      for (const kind of [...allowed, ...blocked]) if (!operationKinds.has(kind)) errors.push(issue('catalog.operation-kind', `catalog capability ${capability.id} uses unknown operation ${kind}`, 'capabilities'));
+      for (const kind of allowed) if (blocked.has(kind)) errors.push(issue('catalog.operation-overlap', `catalog capability ${capability.id} marks ${kind} as both allowed and blocked`, 'capabilities'));
+    }
+  }
+  return errors;
+}
+
+export function catalogCapability(catalog, id) {
+  return catalog?.capabilities?.find((capability) => capability.id === id) ?? null;
+}
+
+export function declarationFromCatalog(catalog, id = 'labels') {
+  const capability = catalogCapability(catalog, id);
+  if (!capability) throw new Error(`Capability ${id} is not declared by the installed SDLC package.`);
+  return {
+    schemaVersion: 1,
+    capabilities: [{
+      id: capability.id,
+      provider: capability.provider,
+      version: capability.version,
+      adapter: capability.adapter,
+      catalogVersion: catalog.package.version,
+      configuration: capability.configuration,
+    }],
+  };
+}

package/src/contracts.mjs

@@ -0,0 +1,39 @@
+export const STAGES = Object.freeze(['triage', 'refine', 'propose', 'implement', 'integrate', 'review']);
+export const GATES = Object.freeze(['triaged', 'ready', 'planned', 'done']);
+export const EVIDENCE_STATUSES = Object.freeze(['passed', 'failed', 'unavailable', 'unconfigured', 'pending-review', 'not-applicable']);
+export const STAGE_STATUSES = Object.freeze(['ready', 'blocked', 'failed', 'passed']);
+
+const stageSet = new Set(STAGES);
+const gateSet = new Set(GATES);
+const evidenceStatusSet = new Set(EVIDENCE_STATUSES);
+const stageStatusSet = new Set(STAGE_STATUSES);
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function validateStageResult(value) {
+  const errors = [];
+  if (!isRecord(value)) return [issue('stage-result.invalid', 'stage result must be an object')];
+  if (value.schemaVersion !== 1) errors.push(issue('stage-result.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  for (const field of ['runId', 'nextAction']) if (typeof value[field] !== 'string' || !value[field].trim()) errors.push(issue(`stage-result.${field}`, `${field} must be a non-empty string`, field));
+  if (!stageSet.has(value.stage)) errors.push(issue('stage-result.stage', `stage must be one of ${STAGES.join(', ')}`, 'stage'));
+  if (!stageStatusSet.has(value.status)) errors.push(issue('stage-result.status', `status must be one of ${STAGE_STATUSES.join(', ')}`, 'status'));
+  if (value.gate !== null && !gateSet.has(value.gate)) errors.push(issue('stage-result.gate', `gate must be one of ${GATES.join(', ')} or null`, 'gate'));
+  if (!Array.isArray(value.evidence)) errors.push(issue('stage-result.evidence', 'evidence must be an array', 'evidence'));
+  else for (const [index, evidence] of value.evidence.entries()) {
+    if (!isRecord(evidence) || typeof evidence.id !== 'string' || !evidence.id.trim() || !evidenceStatusSet.has(evidence.status)) errors.push(issue('stage-result.evidence-item', `evidence[${index}] needs an id and a supported status`, `evidence[${index}]`));
+  }
+  for (const field of ['missingEvidence', 'unavailableChecks', 'pendingReview']) if (!Array.isArray(value[field]) || value[field].some((item) => typeof item !== 'string' || !item.trim())) errors.push(issue(`stage-result.${field}`, `${field} must be an array of names`, field));
+  if (value.input !== undefined && !isRecord(value.input)) errors.push(issue('stage-result.input', 'input must be an object when present', 'input'));
+  if (value.output !== undefined && !isRecord(value.output)) errors.push(issue('stage-result.output', 'output must be an object when present', 'output'));
+  return errors;
+}
+
+export function isValidStageResult(value) {
+  return validateStageResult(value).length === 0;
+}

package/src/control-plane.mjs

@@ -0,0 +1,51 @@
+import { MEMORY_SCOPES } from './memory.mjs';
+import { WORKFLOW_STATES } from './workflow.mjs';
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export function validateControlPlane(value) {
+  const errors = [];
+  if (!isRecord(value)) return [issue('control-plane.invalid', 'control plane must be an object')];
+  if (value.schemaVersion !== 1) errors.push(issue('control-plane.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  if (!isRecord(value.package) || typeof value.package.name !== 'string' || typeof value.package.version !== 'string') errors.push(issue('control-plane.package', 'package needs name and version', 'package'));
+  for (const field of ['routes', 'gates']) if (!Array.isArray(value[field]) || value[field].some((item) => typeof item !== 'string' || !item.trim())) errors.push(issue(`control-plane.${field}`, `${field} must be an array of names`, field));
+  if (!isRecord(value.state) || typeof value.state.provider !== 'string' || !value.state.provider.trim()) errors.push(issue('control-plane.state', 'state.provider is required', 'state'));
+  if (value.state?.states !== undefined && (!Array.isArray(value.state.states) || value.state.states.some((state) => !WORKFLOW_STATES.includes(state)))) errors.push(issue('control-plane.state-states', 'state.states must contain known workflow states', 'state.states'));
+  if (!isRecord(value.memory) || typeof value.memory.provider !== 'string' || !value.memory.provider.trim()) errors.push(issue('control-plane.memory', 'memory.provider is required', 'memory'));
+  if (!Array.isArray(value.memory?.scopes) || value.memory.scopes.length === 0 || value.memory.scopes.some((scope) => !MEMORY_SCOPES.includes(scope))) errors.push(issue('control-plane.memory-scopes', `memory.scopes must contain values from ${MEMORY_SCOPES.join(', ')}`, 'memory.scopes'));
+  if (value.memory?.scopes?.includes('shared') && value.memory.shared !== true) errors.push(issue('control-plane.shared-memory', 'shared memory requires memory.shared=true', 'memory.shared'));
+  if (!isRecord(value.roles)) errors.push(issue('control-plane.roles', 'roles must be an object', 'roles'));
+  else for (const [name, role] of Object.entries(value.roles)) {
+    if (typeof role === 'string' && role.trim()) continue;
+    if (!isRecord(role)) errors.push(issue('control-plane.role', `role ${name} must be an object or provider reference`, `roles.${name}`));
+    else {
+      for (const field of ['inputSchema', 'outputSchema']) if (typeof role[field] !== 'string' || !role[field].trim()) errors.push(issue('control-plane.role-schema', `role ${name} needs ${field}`, `roles.${name}.${field}`));
+      if (!Array.isArray(role.tools)) errors.push(issue('control-plane.role-tools', `role ${name} needs a tools array`, `roles.${name}.tools`));
+      if (!Array.isArray(role.writeScope)) errors.push(issue('control-plane.role-write-scope', `role ${name} needs a writeScope array`, `roles.${name}.writeScope`));
+    }
+  }
+  if (!isRecord(value.adapters)) errors.push(issue('control-plane.adapters', 'adapters must be an object', 'adapters'));
+  return errors;
+}
+
+export function validateLaunchRequest(request, controlPlane) {
+  const errors = [];
+  if (!isRecord(request)) return [issue('launch.invalid', 'launch request must be an object')];
+  for (const field of ['runId', 'role', 'outputSchema']) if (typeof request[field] !== 'string' || !request[field].trim()) errors.push(issue(`launch.${field}`, `${field} must be a non-empty string`, field));
+  const role = controlPlane?.roles?.[request.role];
+  if (!role) errors.push(issue('launch.role', `role ${request.role} is not declared`, 'role'));
+  if (role && request.outputSchema !== role.outputSchema) errors.push(issue('launch.output-schema', `outputSchema does not match role ${request.role}`, 'outputSchema'));
+  if (!Array.isArray(request.tools)) errors.push(issue('launch.tools', 'tools must be an array', 'tools'));
+  else if (role) for (const tool of request.tools) if (!role.tools.includes(tool)) errors.push(issue('launch.tool', `tool ${tool} is not allowed for role ${request.role}`, 'tools'));
+  if (!Array.isArray(request.writeScope)) errors.push(issue('launch.write-scope', 'writeScope must be an array', 'writeScope'));
+  else if (role) for (const path of request.writeScope) if (!role.writeScope.includes(path)) errors.push(issue('launch.write-path', `write path ${path} is not allowed for role ${request.role}`, 'writeScope'));
+  if (!isRecord(request.limits)) errors.push(issue('launch.limits', 'limits must be an object', 'limits'));
+  if (!Array.isArray(request.stopConditions)) errors.push(issue('launch.stop-conditions', 'stopConditions must be an array', 'stopConditions'));
+  return errors;
+}

package/src/decompose.mjs

@@ -0,0 +1,53 @@
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+function orderSlices(slices) {
+  const byId = new Map(slices.map((slice) => [slice.id, slice]));
+  const visiting = new Set();
+  const visited = new Set();
+  const ordered = [];
+  const errors = [];
+  function visit(id) {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) { errors.push(issue('decompose.cycle', `dependency cycle includes ${id}`, 'slices')); return; }
+    visiting.add(id);
+    for (const dependency of byId.get(id)?.dependencies ?? []) if (byId.has(dependency)) visit(dependency);
+    visiting.delete(id);
+    visited.add(id);
+    ordered.push(id);
+  }
+  for (const slice of slices) visit(slice.id);
+  return { ordered, errors };
+}
+
+export function buildDecompositionPlan(input) {
+  const errors = [];
+  if (!isRecord(input)) return { schemaVersion: 1, status: 'invalid', valid: false, canApply: false, errors: [issue('decompose.invalid', 'decomposition input must be an object')] };
+  if (input.schemaVersion !== 1) errors.push(issue('decompose.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  if (!isRecord(input.parent) || typeof input.parent.id !== 'string' || !input.parent.id.trim() || typeof input.parent.title !== 'string' || !input.parent.title.trim()) errors.push(issue('decompose.parent', 'parent needs id and title', 'parent'));
+  if (!Array.isArray(input.slices) || input.slices.length === 0) errors.push(issue('decompose.slices', 'slices must be a non-empty array', 'slices'));
+  const ids = new Set();
+  const slices = Array.isArray(input.slices) ? input.slices.map((slice, index) => {
+    if (!isRecord(slice) || typeof slice.id !== 'string' || !slice.id.trim() || typeof slice.title !== 'string' || !slice.title.trim()) { errors.push(issue('decompose.slice', `slice ${index} needs id and title`, `slices[${index}]`)); return null; }
+    if (ids.has(slice.id)) errors.push(issue('decompose.duplicate', `slice ${slice.id} appears more than once`, `slices[${index}].id`));
+    ids.add(slice.id);
+    if (!Array.isArray(slice.dependencies)) errors.push(issue('decompose.dependencies', `slice ${slice.id} needs a dependencies array`, `slices[${index}].dependencies`));
+    if (!Array.isArray(slice.acceptance) || slice.acceptance.length === 0 || slice.acceptance.some((item) => typeof item !== 'string' || !item.trim())) errors.push(issue('decompose.acceptance', `slice ${slice.id} needs independent acceptance evidence`, `slices[${index}].acceptance`));
+    return { id: slice.id, title: slice.title, acceptance: [...(slice.acceptance ?? [])], dependencies: [...(slice.dependencies ?? [])].sort(), scope: [...(slice.scope ?? [])].sort(), labels: [...(slice.labels ?? [])].sort() };
+  }).filter(Boolean) : [];
+  for (const slice of slices) for (const dependency of slice.dependencies) if (!ids.has(dependency)) errors.push(issue('decompose.unknown-dependency', `slice ${slice.id} depends on unknown slice ${dependency}`, 'slices'));
+  const order = orderSlices(slices);
+  errors.push(...order.errors);
+  const status = errors.length ? 'invalid' : 'ready';
+  return { schemaVersion: 1, status, valid: errors.length === 0, canApply: status === 'ready', parent: input.parent ?? null, slices, order: order.ordered, operations: status === 'ready' ? order.ordered.map((id) => ({ type: 'create-child', parentId: input.parent?.id, sliceId: id })) : [], errors };
+}
+
+export function applyDecompositionPlan(plan) {
+  if (!plan?.canApply) throw new Error('Decomposition plan is not ready to apply. Resolve its errors first.');
+  return { ...plan, applied: true };
+}

package/src/github.mjs

@@ -0,0 +1,67 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export async function ghJson(args, { command = 'gh', cwd } = {}) {
+  const { stdout } = await execFileAsync(command, ['api', ...args], { cwd, maxBuffer: 10 * 1024 * 1024 });
+  return JSON.parse(stdout);
+}
+
+export async function readGithubIssue(repo, number, options = {}) {
+  if (!repo || !number) throw new Error('repo and issue number are required');
+  const issueRecord = await ghJson([`repos/${repo}/issues/${number}`], options);
+  return {
+    schemaVersion: 1,
+    workItem: { id: `GH-${issueRecord.number}`, title: issueRecord.title, type: issueRecord.pull_request ? 'pull-request' : 'issue', url: issueRecord.html_url, state: issueRecord.state },
+    currentLabels: (issueRecord.labels ?? []).map((label) => typeof label === 'string' ? label : label.name).filter(Boolean).sort(),
+    links: { url: issueRecord.html_url, parent: issueRecord.parent ?? null, subIssues: issueRecord.sub_issues ?? [] },
+    dependencies: issueRecord.dependencies ?? [],
+    source: { provider: 'github', repository: repo, number: issueRecord.number },
+  };
+}
+
+export async function readGithubLabels(repo, options = {}) {
+  if (!repo) throw new Error('repo is required');
+  const labels = await ghJson([`repos/${repo}/labels?per_page=100`], options);
+  return Array.isArray(labels) ? labels.map((label) => ({ name: label.name, color: label.color, description: label.description ?? null })).sort((left, right) => left.name.localeCompare(right.name)) : [];
+}
+
+export async function createGithubLabel(repo, label, options = {}) {
+  if (!label?.name) throw new Error('label name is required');
+  if (options.dryRun !== false) return { applied: false, label };
+  const created = await ghJson(['--method', 'POST', `repos/${repo}/labels`, '-f', `name=${label.name}`, '-f', `color=${String(label.color ?? '8B949E').replace(/^#/u, '')}`, '-f', `description=${label.description ?? ''}`], options);
+  return { applied: true, label: { name: created.name, color: created.color, description: created.description ?? null } };
+}
+
+export function mergeGithubTriage(issueRecord, assessment, configuration) {
+  if (!issueRecord || typeof issueRecord !== 'object') return { errors: [issue('github.issue', 'issue metadata is required')] };
+  if (!assessment || typeof assessment !== 'object') return { errors: [issue('github.assessment', 'structured assessment is required')] };
+  return { ...issueRecord, assessment, configuration };
+}
+
+export async function replaceGithubLabels(repo, number, labels, options = {}) {
+  if (!Array.isArray(labels)) throw new Error('labels must be an array');
+  if (options.dryRun !== false) return { applied: false, labels: [...labels] };
+  const { stdout } = await execFileAsync(options.command ?? 'gh', ['api', '--method', 'PUT', `repos/${repo}/issues/${number}/labels`, ...labels.flatMap((label) => ['-f', `labels[]=${label}`])], { cwd: options.cwd, maxBuffer: 10 * 1024 * 1024 });
+  return { applied: true, labels: JSON.parse(stdout).map((label) => label.name).sort() };
+}
+
+export async function createGithubSubIssues(repo, parentNumber, plan, options = {}) {
+  if (!plan?.canApply) throw new Error('Decomposition plan is not ready to apply. Resolve its errors first.');
+  const operations = plan.order.map((id) => {
+    const slice = plan.slices.find((candidate) => candidate.id === id);
+    return { type: 'create-child-issue', parent: Number(parentNumber), sliceId: id, title: slice.title, body: `Parent issue: #${parentNumber}\n\nAcceptance evidence:\n${slice.acceptance.map((item) => `- ${item}`).join('\n')}` };
+  });
+  if (options.dryRun !== false) return { applied: false, operations };
+  const created = [];
+  for (const operation of operations) {
+    const issueRecord = await ghJson(['--method', 'POST', `repos/${repo}/issues`, '-f', `title=${operation.title}`, '-f', `body=${operation.body}`], options);
+    created.push({ ...operation, number: issueRecord.number, url: issueRecord.html_url });
+  }
+  return { applied: true, operations: created };
+}

package/src/memory.mjs

@@ -0,0 +1,22 @@
+export const MEMORY_SCOPES = Object.freeze(['run', 'project', 'shared']);
+const scopeSet = new Set(MEMORY_SCOPES);
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export function validateMemoryRecord(record, policy = {}) {
+  const errors = [];
+  if (!isRecord(record)) return [issue('memory.invalid', 'memory record must be an object')];
+  for (const field of ['id', 'owner', 'source', 'confidence', 'retention', 'sensitivity']) if (typeof record[field] !== 'string' || !record[field].trim()) errors.push(issue(`memory.${field}`, `${field} must be a non-empty string`, field));
+  if (!scopeSet.has(record.scope)) errors.push(issue('memory.scope', `scope must be one of ${MEMORY_SCOPES.join(', ')}`, 'scope'));
+  if (record.scope === 'run' && (typeof record.runId !== 'string' || !record.runId.trim())) errors.push(issue('memory.run-id', 'run-scoped memory needs runId', 'runId'));
+  if (record.scope === 'project' && (typeof record.projectId !== 'string' || !record.projectId.trim())) errors.push(issue('memory.project-id', 'project-scoped memory needs projectId', 'projectId'));
+  if (record.scope === 'shared' && policy.shared !== true) errors.push(issue('memory.shared-disabled', 'shared memory is not enabled by the control-plane policy', 'scope'));
+  if (!isRecord(record.value)) errors.push(issue('memory.value', 'value must be an object', 'value'));
+  return errors;
+}

package/src/reconcile.mjs

@@ -0,0 +1,169 @@
+import { createHash } from 'node:crypto';
+import { validateConfiguration, suggestedLabelColors } from './triage.mjs';
+
+const CAPABILITY_ID = 'labels';
+const SUPPORTED_PROVIDER = 'github';
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (!isRecord(value)) return JSON.stringify(value);
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`;
+}
+
+function digest(value) {
+  return createHash('sha256').update(stable(value)).digest('hex');
+}
+
+function color(value) {
+  return typeof value === 'string' ? value.replace(/^#/u, '').toUpperCase() : null;
+}
+
+function comparableName(value) {
+  return String(value).toLowerCase().replace(/[^a-z0-9]/gu, '');
+}
+
+function normalizeExisting(labels) {
+  const errors = [];
+  if (!Array.isArray(labels)) return { labels: [], errors: [issue('labels.existing', 'existing labels must be an array', 'existing')] };
+  const seen = new Set();
+  const normalized = [];
+  for (const [index, item] of labels.entries()) {
+    const value = typeof item === 'string' ? { name: item } : item;
+    if (!isRecord(value) || typeof value.name !== 'string' || !value.name.trim()) {
+      errors.push(issue('labels.existing-item', `existing label ${index} needs a name`, `existing[${index}]`));
+      continue;
+    }
+    const name = value.name.trim();
+    if (seen.has(name)) errors.push(issue('labels.existing-duplicate', `existing label ${name} appears more than once`, 'existing'));
+    seen.add(name);
+    normalized.push({ name, color: color(value.color), description: value.description ?? null });
+  }
+  normalized.sort((left, right) => left.name.localeCompare(right.name));
+  return { labels: normalized, errors };
+}
+
+function capabilityConfig(capability) {
+  return capability?.configuration && isRecord(capability.configuration) ? capability.configuration : capability;
+}
+
+export function validateCapabilityDeclaration(declaration) {
+  const errors = [];
+  if (!isRecord(declaration)) return [issue('capabilities.invalid', 'capability declaration must be an object')];
+  if (declaration.schemaVersion !== 1) errors.push(issue('capabilities.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  if (!Array.isArray(declaration.capabilities) || declaration.capabilities.length === 0) {
+    errors.push(issue('capabilities.list', 'capabilities must be a non-empty array', 'capabilities'));
+    return errors;
+  }
+  const selected = declaration.capabilities.filter((capability) => capability?.id === CAPABILITY_ID);
+  if (selected.length !== 1) errors.push(issue('capabilities.labels-selection', 'exactly one labels capability must be selected', 'capabilities'));
+  for (const [index, capability] of declaration.capabilities.entries()) {
+    if (!isRecord(capability) || typeof capability.id !== 'string' || !capability.id.trim()) {
+      errors.push(issue('capability.invalid', `capability ${index} needs an id`, `capabilities[${index}]`));
+      continue;
+    }
+    if (typeof capability.provider !== 'string' || !capability.provider.trim()) errors.push(issue('capability.provider', `capability ${capability.id} needs a provider`, `capabilities[${index}].provider`));
+    if (typeof capability.version !== 'string' || !capability.version.trim()) errors.push(issue('capability.version', `capability ${capability.id} needs a version`, `capabilities[${index}].version`));
+  }
+  const labels = selected[0];
+  if (labels) errors.push(...validateConfiguration(capabilityConfig(labels)).errors);
+  return errors;
+}
+
+export function buildLabelReconciliationPlan(declaration, existingLabels, previousRecord = null) {
+  const errors = validateCapabilityDeclaration(declaration);
+  const capability = declaration?.capabilities?.find((item) => item?.id === CAPABILITY_ID);
+  const existing = normalizeExisting(existingLabels);
+  errors.push(...existing.errors);
+  if (capability && capability.provider !== SUPPORTED_PROVIDER) errors.push(issue('capability.provider-unsupported', `labels provider ${capability.provider} is not supported by this adapter`, 'capabilities'));
+  const configuration = capabilityConfig(capability);
+  const desired = (Array.isArray(configuration?.labels) ? configuration.labels : []).filter((label) => isRecord(label) && typeof label.name === 'string' && label.name.trim()).map((label) => ({
+    name: label.name.trim(),
+    color: color(label.color ?? suggestedLabelColors[label.name]),
+    description: label.description ?? null,
+    role: label.role,
+    dimension: label.dimension,
+    value: label.value,
+  })).sort((left, right) => left.name.localeCompare(right.name));
+  const existingByName = new Map(existing.labels.map((label) => [label.name, label]));
+  const existingByComparableName = new Map();
+  for (const label of existing.labels) {
+    const key = comparableName(label.name);
+    existingByComparableName.set(key, [...(existingByComparableName.get(key) ?? []), label]);
+  }
+  const desiredNames = new Set();
+  const changes = [];
+  const operations = [];
+  for (const label of desired) {
+    if (desiredNames.has(label.name)) {
+      errors.push(issue('labels.desired-duplicate', `desired label ${label.name} appears more than once`, 'capabilities'));
+      continue;
+    }
+    desiredNames.add(label.name);
+    const current = existingByName.get(label.name);
+    if (!current) {
+      const equivalents = existingByComparableName.get(comparableName(label.name)) ?? [];
+      if (equivalents.length) {
+        changes.push({ name: label.name, status: 'conflict', operation: 'ambiguous', desired: label, candidates: equivalents });
+        continue;
+      }
+      changes.push({ name: label.name, status: 'missing', operation: 'create', desired: label });
+      operations.push({ type: 'create-label', kind: 'create', name: label.name, color: label.color ?? '8B949E', description: label.description ?? '' });
+      continue;
+    }
+    const customized = (label.color !== null && current.color !== label.color) || (label.description !== null && current.description !== label.description);
+    changes.push({ name: label.name, status: customized ? 'customized' : 'unchanged', operation: 'preserve', blockedOperations: customized ? ['modify'] : [], existing: current, desired: label });
+  }
+  for (const label of existing.labels) if (!desiredNames.has(label.name)) changes.push({ name: label.name, status: 'preserved', operation: 'preserve', existing: label });
+  changes.sort((left, right) => left.name.localeCompare(right.name));
+  const target = [...existing.labels, ...operations.map((operation) => ({ name: operation.name, color: operation.color, description: operation.description }))].sort((left, right) => left.name.localeCompare(right.name));
+  const observedHash = digest(existing.labels);
+  const targetHash = digest(target);
+  const drift = previousRecord && previousRecord.targetHash !== observedHash
+    ? { status: 'drift', expectedHash: previousRecord.targetHash, observedHash }
+    : { status: 'none', expectedHash: previousRecord?.targetHash ?? null, observedHash };
+  const conflicts = changes.filter((change) => change.status === 'conflict');
+  const status = errors.length ? 'invalid' : conflicts.length ? 'blocked' : 'ready';
+  return {
+    schemaVersion: 1,
+    status,
+    valid: errors.length === 0,
+    canApply: status === 'ready',
+    capability: capability ? { id: capability.id, provider: capability.provider, version: capability.version } : null,
+    desiredHash: digest(desired),
+    observedHash,
+    targetHash,
+    target,
+    drift,
+    operationPolicy: capability?.operations ?? { allowed: ['create', 'preserve'], blocked: ['modify', 'rename', 'remove', 'ambiguous'] },
+    blockedOperations: changes.flatMap((change) => change.blockedOperations ?? []),
+    changes,
+    operations,
+    errors,
+    record: {
+      schemaVersion: 1,
+      capability: capability ? { id: capability.id, provider: capability.provider, version: capability.version } : null,
+      desiredHash: digest(desired),
+      observedHash: targetHash,
+      targetHash,
+      operations: operations.map(({ type, kind, name, color: labelColor, description }) => ({ type, kind, name, color: labelColor, description })),
+      blockedOperations: changes.flatMap((change) => change.blockedOperations ?? []),
+      verified: false,
+    },
+  };
+}
+
+export function applyLabelReconciliationPlan(plan, existingLabels) {
+  if (!plan?.canApply) throw new Error('Label reconciliation is not ready to apply. Resolve its errors first.');
+  const existing = normalizeExisting(existingLabels);
+  if (existing.errors.length) throw new Error(existing.errors.map((error) => error.message).join('\n'));
+  const names = new Set(existing.labels.map((label) => label.name));
+  return [...existing.labels, ...plan.operations.filter((operation) => !names.has(operation.name)).map((operation) => ({ name: operation.name, color: operation.color, description: operation.description }))].sort((left, right) => left.name.localeCompare(right.name));
+}

package/src/routes.mjs

@@ -0,0 +1,22 @@
+import { GATES, STAGES } from './contracts.mjs';
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export function validateRouteDescriptor(route, contract = {}) {
+  const errors = [];
+  if (!route || typeof route !== 'object') return [issue('route.invalid', 'route must be an object')];
+  if (typeof route.id !== 'string' || !route.id.trim()) errors.push(issue('route.id', 'route id must be a non-empty string', 'id'));
+  if (!Array.isArray(route.stages) || route.stages.length === 0 || route.stages.some((stage) => !STAGES.includes(stage))) errors.push(issue('route.stages', `stages must use ${STAGES.join(', ')}`, 'stages'));
+  if (!Array.isArray(route.humanGates) || route.humanGates.some((gate) => !GATES.includes(gate))) errors.push(issue('route.gates', `humanGates must use ${GATES.join(', ')}`, 'humanGates'));
+  if (contract.stages && route.stages?.some((stage, index) => stage !== contract.stages[index])) errors.push(issue('route.order', 'route stages must preserve the package stage order', 'stages'));
+  return errors;
+}
+
+export function buildRoutePlan(route, { available = [], decisions = {} } = {}) {
+  const errors = validateRouteDescriptor(route);
+  const prerequisites = (route.requires ?? []).map((requirement) => ({ id: requirement, status: available.includes(requirement) ? 'passed' : 'pending-review' }));
+  const status = errors.length ? 'invalid' : prerequisites.some((item) => item.status !== 'passed') ? 'blocked' : 'ready';
+  return { schemaVersion: 1, status, valid: errors.length === 0, canRun: status === 'ready', route: route.id, stages: [...(route.stages ?? [])], humanGates: [...(route.humanGates ?? [])], requires: prerequisites, decisions, errors };
+}