@snappedly-tools/shipyard 0.8.0 → 0.9.1

package/dist/chunk-NQRFVKCU.js

@@ -0,0 +1,1840 @@
+import { createHash } from 'crypto';
+
+// src/workflow/contracts/index.ts
+
+// src/workflow/shared.ts
+var sameWorkIdentity = (left, right) => left.repository === right.repository && left.itemId === right.itemId && left.kind === right.kind;
+var sameRevision = (left, right) => left.branch === right.branch && left.sha === right.sha;
+var isBlockingFinding = (finding) => finding.severity !== "info" && (finding.disposition === "open" || finding.disposition === "deferred");
+var requiredCheckNames = (policy) => policy.checks.filter((check) => check.required).map((check) => check.name);
+var deepFreeze = (value) => {
+  if (typeof value !== "object" || value === null) return value;
+  for (const child of Object.values(value)) {
+    deepFreeze(child);
+  }
+  return Object.freeze(value);
+};
+
+// src/workflow/contracts/index.ts
+var WORKFLOW_CONTRACT_VERSION = 1;
+var isAuthorizationAllowed = (brief, policy) => brief.authorization.status === "approved" && brief.authorization.actor !== void 0 && brief.authorization.actor.trim().length > 0 && brief.authorization.approvedAt !== void 0 && brief.authorization.approvedAt.trim().length > 0 && brief.authorization.actorRole !== void 0 && policy.authorization.allowedActors.includes(brief.authorization.actorRole);
+var ContractValidationError = class extends Error {
+  issues;
+  constructor(message, issues = []) {
+    super(message);
+    this.name = "ContractValidationError";
+    this.issues = issues.length > 0 ? issues : [message];
+  }
+};
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var nonEmptyString = (value, path) => {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new ContractValidationError(`${path} must be a non-empty string`);
+  }
+  return value;
+};
+var optionalString = (value, path) => {
+  if (value === void 0) return void 0;
+  return nonEmptyString(value, path);
+};
+var enumValue = (value, values, path) => {
+  if (typeof value !== "string" || !values.includes(value)) {
+    throw new ContractValidationError(
+      `${path} must be one of: ${values.join(", ")}`
+    );
+  }
+  return value;
+};
+var stringArray = (value, path) => {
+  if (!Array.isArray(value)) {
+    throw new ContractValidationError(`${path} must be an array`);
+  }
+  return value.map(
+    (entry, index) => nonEmptyString(entry, `${path}[${index}]`)
+  );
+};
+var enumArray = (value, values, path) => stringArray(value, path).map(
+  (entry, index) => enumValue(entry, values, `${path}[${index}]`)
+);
+var positiveInteger = (value, path) => {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new ContractValidationError(`${path} must be a positive integer`);
+  }
+  return value;
+};
+var nonNegativeInteger = (value, path) => {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new ContractValidationError(`${path} must be a non-negative integer`);
+  }
+  return value;
+};
+var contractVersion = (value) => {
+  if (value !== WORKFLOW_CONTRACT_VERSION) {
+    throw new ContractValidationError(
+      `Unsupported workflow contract version: ${String(value)}`
+    );
+  }
+  return WORKFLOW_CONTRACT_VERSION;
+};
+var parseIdentity = (value, path = "identity") => {
+  if (!isRecord(value)) {
+    throw new ContractValidationError(`${path} must be an object`);
+  }
+  return {
+    repository: nonEmptyString(value.repository, `${path}.repository`),
+    itemId: nonEmptyString(value.itemId, `${path}.itemId`),
+    kind: enumValue(
+      value.kind,
+      ["planning-spec", "executable-issue", "pr-repair"],
+      `${path}.kind`
+    )
+  };
+};
+var parseRevision = (value, path) => {
+  if (!isRecord(value)) {
+    throw new ContractValidationError(`${path} must be an object`);
+  }
+  return {
+    branch: nonEmptyString(value.branch, `${path}.branch`),
+    sha: nonEmptyString(value.sha, `${path}.sha`)
+  };
+};
+var parseAuthorization = (value) => {
+  if (!isRecord(value)) {
+    throw new ContractValidationError("authorization must be an object");
+  }
+  const result = {
+    status: enumValue(
+      value.status,
+      ["pending", "approved", "withdrawn"],
+      "authorization.status"
+    ),
+    actor: optionalString(value.actor, "authorization.actor"),
+    actorRole: value.actorRole === void 0 ? void 0 : enumValue(
+      value.actorRole,
+      ["maintainer", "owner", "policy"],
+      "authorization.actorRole"
+    ),
+    approvedAt: optionalString(value.approvedAt, "authorization.approvedAt")
+  };
+  if (result.status === "approved" && (!result.actor || !result.approvedAt)) {
+    throw new ContractValidationError(
+      "approved authorization requires actor and approvedAt"
+    );
+  }
+  return result;
+};
+var parseSource = (value) => {
+  if (!isRecord(value)) {
+    throw new ContractValidationError("source must be an object");
+  }
+  return {
+    provider: enumValue(
+      value.provider,
+      ["github", "slack", "manual"],
+      "source.provider"
+    ),
+    repository: nonEmptyString(value.repository, "source.repository"),
+    itemId: nonEmptyString(value.itemId, "source.itemId"),
+    url: optionalString(value.url, "source.url"),
+    originalBody: nonEmptyString(value.originalBody, "source.originalBody"),
+    author: optionalString(value.author, "source.author")
+  };
+};
+var parseVerification = (value) => {
+  if (!isRecord(value)) {
+    throw new ContractValidationError("verification must be an object");
+  }
+  return {
+    checks: stringArray(value.checks, "verification.checks"),
+    artifacts: stringArray(value.artifacts, "verification.artifacts")
+  };
+};
+var briefHashInput = (brief) => canonicalJson(brief);
+var canonicalJson = (value) => {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+  }
+  if (isRecord(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+};
+var sha256 = (value) => createHash("sha256").update(value).digest("hex");
+var createWorkBrief = (input) => {
+  const withoutHash = {
+    contractVersion: WORKFLOW_CONTRACT_VERSION,
+    id: input.id ?? `${input.identity.repository}:${input.identity.kind}:${input.identity.itemId}`,
+    revision: input.revision ?? 1,
+    identity: parseIdentity(input.identity),
+    source: parseSource(input.source),
+    problem: nonEmptyString(input.problem, "problem"),
+    evidence: stringArray(input.evidence, "evidence"),
+    acceptanceCriteria: stringArray(
+      input.acceptanceCriteria,
+      "acceptanceCriteria"
+    ),
+    exclusions: stringArray(input.exclusions, "exclusions"),
+    risk: enumValue(
+      input.risk,
+      ["low", "medium", "high", "critical", "unknown"],
+      "risk"
+    ),
+    ...input.scope === void 0 ? {} : {
+      scope: enumValue(
+        input.scope,
+        ["small", "substantial", "unknown"],
+        "scope"
+      )
+    },
+    verification: parseVerification(input.verification),
+    unresolvedQuestions: stringArray(
+      input.unresolvedQuestions,
+      "unresolvedQuestions"
+    ),
+    authorization: parseAuthorization(input.authorization),
+    base: parseRevision(input.base, "base"),
+    policyRevision: nonEmptyString(input.policyRevision, "policyRevision"),
+    skillRevision: nonEmptyString(input.skillRevision, "skillRevision"),
+    createdAt: nonEmptyString(input.createdAt, "createdAt")
+  };
+  if (withoutHash.identity.repository !== withoutHash.source.repository || withoutHash.identity.itemId !== withoutHash.source.itemId) {
+    throw new ContractValidationError(
+      "work brief source must identify the same repository and item as its identity"
+    );
+  }
+  const brief = {
+    ...withoutHash,
+    hash: sha256(briefHashInput(withoutHash))
+  };
+  return parseWorkBrief(brief);
+};
+var parseWorkBrief = (value) => {
+  if (!isRecord(value)) {
+    throw new ContractValidationError("work brief must be an object");
+  }
+  const parsedWithoutHash = {
+    contractVersion: contractVersion(value.contractVersion),
+    id: nonEmptyString(value.id, "id"),
+    revision: positiveInteger(value.revision, "revision"),
+    identity: parseIdentity(value.identity),
+    source: parseSource(value.source),
+    problem: nonEmptyString(value.problem, "problem"),
+    evidence: stringArray(value.evidence, "evidence"),
+    acceptanceCriteria: stringArray(
+      value.acceptanceCriteria,
+      "acceptanceCriteria"
+    ),
+    exclusions: stringArray(value.exclusions, "exclusions"),
+    risk: enumValue(
+      value.risk,
+      ["low", "medium", "high", "critical", "unknown"],
+      "risk"
+    ),
+    ...value.scope === void 0 ? {} : {
+      scope: enumValue(
+        value.scope,
+        ["small", "substantial", "unknown"],
+        "scope"
+      )
+    },
+    verification: parseVerification(value.verification),
+    unresolvedQuestions: stringArray(
+      value.unresolvedQuestions,
+      "unresolvedQuestions"
+    ),
+    authorization: parseAuthorization(value.authorization),
+    base: parseRevision(value.base, "base"),
+    policyRevision: nonEmptyString(value.policyRevision, "policyRevision"),
+    skillRevision: nonEmptyString(value.skillRevision, "skillRevision"),
+    createdAt: nonEmptyString(value.createdAt, "createdAt")
+  };
+  const hash = nonEmptyString(value.hash, "hash");
+  if (parsedWithoutHash.identity.repository !== parsedWithoutHash.source.repository || parsedWithoutHash.identity.itemId !== parsedWithoutHash.source.itemId) {
+    throw new ContractValidationError(
+      "work brief source must identify the same repository and item as its identity"
+    );
+  }
+  const expectedHash = sha256(briefHashInput(parsedWithoutHash));
+  if (hash !== expectedHash) {
+    throw new ContractValidationError("work brief hash does not match content");
+  }
+  return { ...parsedWithoutHash, hash };
+};
+var parsePhaseBudget = (value, path) => {
+  if (!isRecord(value)) {
+    throw new ContractValidationError(`${path} must be an object`);
+  }
+  return {
+    maxAttempts: positiveInteger(value.maxAttempts, `${path}.maxAttempts`),
+    timeoutSeconds: positiveInteger(
+      value.timeoutSeconds,
+      `${path}.timeoutSeconds`
+    )
+  };
+};
+var workflowPhases = [
+  "triage",
+  "implementation",
+  "checking",
+  "review",
+  "repair",
+  "handoff",
+  "merge",
+  "release-verification"
+];
+var parseRepositoryPolicy = (value) => {
+  if (!isRecord(value)) {
+    throw new ContractValidationError("repository policy must be an object");
+  }
+  if (!isRecord(value.authorization)) {
+    throw new ContractValidationError("policy.authorization must be an object");
+  }
+  if (!isRecord(value.worker)) {
+    throw new ContractValidationError("policy.worker must be an object");
+  }
+  const workerModels = value.worker.models === void 0 ? void 0 : (() => {
+    if (value.worker.model !== void 0) {
+      throw new ContractValidationError(
+        "policy.worker.model cannot be combined with policy.worker.models"
+      );
+    }
+    if (!isRecord(value.worker.models)) {
+      throw new ContractValidationError(
+        "policy.worker.models must be an object"
+      );
+    }
+    return {
+      routine: nonEmptyString(
+        value.worker.models.routine,
+        "policy.worker.models.routine"
+      ),
+      strong: nonEmptyString(
+        value.worker.models.strong,
+        "policy.worker.models.strong"
+      )
+    };
+  })();
+  if (!Array.isArray(value.checks)) {
+    throw new ContractValidationError("policy.checks must be an array");
+  }
+  const phaseBudgetRecord = value.phaseBudgets;
+  if (!isRecord(phaseBudgetRecord)) {
+    throw new ContractValidationError("policy.phaseBudgets must be an object");
+  }
+  if (!isRecord(value.repairBudget)) {
+    throw new ContractValidationError("policy.repairBudget must be an object");
+  }
+  const phaseBudgets = Object.fromEntries(
+    workflowPhases.map((phase) => {
+      if (!(phase in phaseBudgetRecord)) {
+        throw new ContractValidationError(
+          `policy.phaseBudgets.${phase} is required`
+        );
+      }
+      return [
+        phase,
+        parsePhaseBudget(
+          phaseBudgetRecord[phase],
+          `policy.phaseBudgets.${phase}`
+        )
+      ];
+    })
+  );
+  const checks = value.checks.map((check, index) => {
+    if (!isRecord(check)) {
+      throw new ContractValidationError(
+        `policy.checks[${index}] must be an object`
+      );
+    }
+    return {
+      name: nonEmptyString(check.name, `policy.checks[${index}].name`),
+      command: nonEmptyString(check.command, `policy.checks[${index}].command`),
+      required: typeof check.required === "boolean" ? check.required : (() => {
+        throw new ContractValidationError(
+          `policy.checks[${index}].required must be a boolean`
+        );
+      })()
+    };
+  });
+  const allowedActors = stringArray(
+    value.authorization.allowedActors,
+    "policy.authorization.allowedActors"
+  ).map(
+    (actor) => enumValue(
+      actor,
+      ["maintainer", "owner", "policy"],
+      "policy.authorization.allowedActors"
+    )
+  );
+  const autoStartRisk = stringArray(
+    value.authorization.autoStartRisk,
+    "policy.authorization.autoStartRisk"
+  ).map(
+    (risk) => enumValue(
+      risk,
+      ["low", "medium", "high", "critical"],
+      "policy.authorization.autoStartRisk"
+    )
+  );
+  const required = value.authorization.required;
+  if (typeof required !== "boolean") {
+    throw new ContractValidationError(
+      "policy.authorization.required must be a boolean"
+    );
+  }
+  const maxBatches = positiveInteger(
+    value.repairBudget.maxBatches,
+    "policy.repairBudget.maxBatches"
+  );
+  const maxFollowUps = nonNegativeInteger(
+    value.repairBudget.maxFollowUps,
+    "policy.repairBudget.maxFollowUps"
+  );
+  return {
+    contractVersion: contractVersion(value.contractVersion),
+    repository: nonEmptyString(value.repository, "policy.repository"),
+    revision: nonEmptyString(value.revision, "policy.revision"),
+    baseBranch: nonEmptyString(value.baseBranch, "policy.baseBranch"),
+    issueClosure: enumValue(
+      value.issueClosure,
+      [
+        "merge-and-ci",
+        "staging-verification",
+        "production-verification"
+      ],
+      "policy.issueClosure"
+    ),
+    authorization: { required, allowedActors, autoStartRisk },
+    worker: {
+      provider: nonEmptyString(value.worker.provider, "policy.worker.provider"),
+      ...workerModels === void 0 ? { model: nonEmptyString(value.worker.model, "policy.worker.model") } : { models: workerModels },
+      sandbox: nonEmptyString(value.worker.sandbox, "policy.worker.sandbox"),
+      skillRevision: nonEmptyString(
+        value.worker.skillRevision,
+        "policy.worker.skillRevision"
+      )
+    },
+    checks,
+    phaseBudgets,
+    repairBudget: { maxBatches, maxFollowUps }
+  };
+};
+var createRepositoryPolicy = (input) => parseRepositoryPolicy({
+  contractVersion: WORKFLOW_CONTRACT_VERSION,
+  ...input
+});
+var resolveAgentSelection = (policy, phase, risk, scope) => {
+  const role = phase === "review" && !(risk === "low" && scope === "small") ? "strong" : "routine";
+  const worker = policy.worker;
+  const modelPath = worker.models ? `policy.worker.models.${role}` : "policy.worker.model";
+  return Object.freeze({
+    provider: nonEmptyString(worker.provider, "policy.worker.provider"),
+    model: nonEmptyString(worker.models?.[role] ?? worker.model, modelPath),
+    role
+  });
+};
+var parseCheckEvidence = (value) => {
+  if (!isRecord(value)) {
+    throw new ContractValidationError("check evidence must be an object");
+  }
+  const status = enumValue(
+    value.status,
+    ["passed", "failed", "incomplete", "blocked", "unknown"],
+    "check.status"
+  );
+  const summary = nonEmptyString(value.summary, "check.summary");
+  const exitCode = value.exitCode === void 0 ? void 0 : nonNegativeInteger(value.exitCode, "check.exitCode");
+  return {
+    name: nonEmptyString(value.name, "check.name"),
+    command: nonEmptyString(value.command, "check.command"),
+    status,
+    summary,
+    baseSha: optionalString(value.baseSha, "check.baseSha"),
+    headSha: optionalString(value.headSha, "check.headSha"),
+    briefHash: optionalString(value.briefHash, "check.briefHash"),
+    startedAt: optionalString(value.startedAt, "check.startedAt"),
+    completedAt: optionalString(value.completedAt, "check.completedAt"),
+    exitCode,
+    artifactRefs: value.artifactRefs === void 0 ? void 0 : stringArray(value.artifactRefs, "check.artifactRefs")
+  };
+};
+var allowedTransitions = {
+  queued: ["waiting-info", "authorized", "cancelled", "blocked", "failed"],
+  "waiting-info": ["queued", "authorized", "cancelled"],
+  authorized: ["implementing", "waiting-info", "cancelled", "blocked"],
+  implementing: ["checking", "waiting-info", "blocked", "failed", "cancelled"],
+  checking: ["reviewing", "repairing", "blocked", "failed", "cancelled"],
+  reviewing: ["repairing", "human-review", "blocked", "failed", "cancelled"],
+  repairing: ["checking", "reviewing", "blocked", "failed", "cancelled"],
+  "human-review": ["merged", "repairing", "blocked", "cancelled"],
+  merged: ["release-verifying", "completed", "failed", "blocked"],
+  "release-verifying": ["completed", "failed", "blocked"],
+  completed: [],
+  failed: [],
+  blocked: [],
+  cancelled: []
+};
+var allRequiredChecksPassed = (context) => {
+  const checks = context.checks;
+  if (checks === void 0) return false;
+  if (context.requiredCheckNames === void 0) {
+    return checks.length > 0 && checks.every((check) => check.status === "passed");
+  }
+  if (context.requiredCheckNames.length > 0 && context.checkCandidate === void 0) {
+    return false;
+  }
+  return context.requiredCheckNames.every(
+    (name) => checks.some(
+      (check) => check.name === name && check.status === "passed" && (context.checkCandidate === void 0 || check.baseSha === context.checkCandidate.baseSha && check.headSha === context.checkCandidate.headSha && check.briefHash === context.checkCandidate.briefHash)
+    )
+  );
+};
+var requireTransition = (from, to, context) => {
+  if (!allowedTransitions[from].includes(to)) {
+    throw new ContractValidationError(
+      `Transition from ${from} to ${to} is not allowed`
+    );
+  }
+  if (to === "implementing") {
+    if (context.kind !== "executable-issue") {
+      throw new ContractValidationError(
+        "Only an executable issue may enter implementation; planning spec and PR repair are separate flows"
+      );
+    }
+    if (context.authorization !== "approved") {
+      throw new ContractValidationError(
+        "Implementation requires approved authorization"
+      );
+    }
+  }
+  if (to === "reviewing" && !allRequiredChecksPassed(context)) {
+    const unknown = context.checks?.find((check) => check.status === "unknown");
+    throw new ContractValidationError(
+      unknown ? `Cannot review while check ${unknown.name} is unknown` : "Cannot review until all required checks pass"
+    );
+  }
+  if (to === "human-review") {
+    if (!allRequiredChecksPassed(context)) {
+      throw new ContractValidationError(
+        "Human review requires a complete set of passing checks"
+      );
+    }
+    if (context.review?.outcome !== "passed" || context.review.axes.length === 0 || context.review.findings.some(isBlockingFinding)) {
+      throw new ContractValidationError(
+        "Human review requires every review axis to pass and blocking findings to be disposed"
+      );
+    }
+    if (context.currentHeadSha !== void 0 && context.assignedHeadSha !== void 0 && context.currentHeadSha !== context.assignedHeadSha) {
+      throw new ContractValidationError(
+        "Human review evidence is stale for the current candidate head"
+      );
+    }
+  }
+};
+var createAssignment = (input) => {
+  const brief = parseWorkBrief(input.brief);
+  if (brief.identity.kind === "planning-spec") {
+    throw new ContractValidationError(
+      "A planning spec cannot receive an execution assignment"
+    );
+  }
+  if (input.phase === "implementation" && brief.identity.kind !== "executable-issue") {
+    throw new ContractValidationError(
+      "PR repair work must use the repair phase; planning spec cannot be implemented"
+    );
+  }
+  if (input.phase === "implementation" && !isAuthorizationAllowed(brief, input.policy)) {
+    throw new ContractValidationError(
+      "Implementation assignments require approved authorization"
+    );
+  }
+  if (input.policy.repository !== brief.identity.repository) {
+    throw new ContractValidationError(
+      "Assignment policy repository does not match work identity"
+    );
+  }
+  if (["checking", "review", "handoff", "merge"].includes(input.phase) && input.head === void 0) {
+    throw new ContractValidationError(
+      `${input.phase} assignments require an immutable candidate head`
+    );
+  }
+  const assignment = {
+    contractVersion: WORKFLOW_CONTRACT_VERSION,
+    id: nonEmptyString(input.id, "assignment.id"),
+    phase: input.phase,
+    attempt: positiveInteger(input.attempt, "assignment.attempt"),
+    identity: brief.identity,
+    briefId: brief.id,
+    briefRevision: brief.revision,
+    briefHash: brief.hash,
+    policyRevision: input.policy.revision,
+    skillRevision: brief.skillRevision,
+    agentSelection: resolveAgentSelection(
+      input.policy,
+      input.phase,
+      brief.risk,
+      brief.scope
+    ),
+    base: brief.base,
+    head: input.head,
+    createdAt: nonEmptyString(input.createdAt, "assignment.createdAt")
+  };
+  return Object.freeze(assignment);
+};
+var parsePhaseResult = (value) => {
+  if (!isRecord(value)) {
+    throw new ContractValidationError("phase result must be an object");
+  }
+  contractVersion(value.contractVersion);
+  const outcome = enumValue(
+    value.outcome,
+    ["completed", "needs-info", "blocked", "failed", "cancelled"],
+    "phase result.outcome"
+  );
+  const evidence = stringArray(value.evidence, "phase result.evidence");
+  const commits = stringArray(value.commits, "phase result.commits");
+  if (outcome === "completed" && evidence.length === 0 && commits.length === 0) {
+    throw new ContractValidationError(
+      "A completed phase requires evidence; zero commits alone cannot mean success"
+    );
+  }
+  const checksValue = value.checks;
+  if (!Array.isArray(checksValue)) {
+    throw new ContractValidationError("phase result.checks must be an array");
+  }
+  const checks = checksValue.map(parseCheckEvidence);
+  return {
+    contractVersion: WORKFLOW_CONTRACT_VERSION,
+    assignmentId: nonEmptyString(
+      value.assignmentId,
+      "phase result.assignmentId"
+    ),
+    phase: enumValue(
+      value.phase,
+      [
+        "triage",
+        "implementation",
+        "checking",
+        "review",
+        "repair",
+        "handoff",
+        "merge",
+        "release-verification"
+      ],
+      "phase result.phase"
+    ),
+    outcome,
+    identity: parseIdentity(value.identity, "phase result.identity"),
+    briefHash: nonEmptyString(value.briefHash, "phase result.briefHash"),
+    base: value.base === void 0 ? void 0 : parseRevision(value.base, "phase result.base"),
+    head: value.head === void 0 ? void 0 : parseRevision(value.head, "phase result.head"),
+    summary: nonEmptyString(value.summary, "phase result.summary"),
+    evidence,
+    checks,
+    commits,
+    artifacts: stringArray(value.artifacts, "phase result.artifacts"),
+    questions: stringArray(value.questions, "phase result.questions"),
+    findings: Array.isArray(value.findings) ? value.findings.map(parseFinding) : (() => {
+      throw new ContractValidationError(
+        "phase result.findings must be an array"
+      );
+    })(),
+    reviewAxes: value.reviewAxes === void 0 ? void 0 : enumArray(
+      value.reviewAxes,
+      ["standards", "spec", "interface"],
+      "phase result.reviewAxes"
+    ),
+    completedAt: nonEmptyString(value.completedAt, "phase result.completedAt")
+  };
+};
+var parseFinding = (value) => {
+  if (!isRecord(value)) {
+    throw new ContractValidationError("finding must be an object");
+  }
+  return {
+    id: nonEmptyString(value.id, "finding.id"),
+    severity: enumValue(
+      value.severity,
+      ["info", "low", "medium", "high", "critical"],
+      "finding.severity"
+    ),
+    axis: enumValue(
+      value.axis,
+      ["standards", "spec", "interface"],
+      "finding.axis"
+    ),
+    disposition: enumValue(
+      value.disposition,
+      ["open", "fixed", "rejected", "accepted", "deferred"],
+      "finding.disposition"
+    ),
+    title: nonEmptyString(value.title, "finding.title"),
+    evidence: nonEmptyString(value.evidence, "finding.evidence"),
+    location: optionalString(value.location, "finding.location"),
+    requirement: optionalString(value.requirement, "finding.requirement"),
+    verification: optionalString(value.verification, "finding.verification")
+  };
+};
+
+// src/workflow/handoff/index.ts
+var defaultAxes = ["standards", "spec"];
+var isFreshTimestamp = (value, now, freshnessWindowSeconds) => {
+  const timestamp = Date.parse(value);
+  const current = Date.parse(now);
+  return Number.isFinite(timestamp) && Number.isFinite(current) && timestamp <= current && current - timestamp <= freshnessWindowSeconds * 1e3;
+};
+var implementationEvidence = (job, candidate) => [...job.phaseResults].reverse().find(
+  (result) => result.outcome === "completed" && (result.phase === "implementation" || result.phase === "repair") && result.base !== void 0 && result.head !== void 0 && sameRevision(result.base, candidate.base) && sameRevision(result.head, candidate.head) && result.briefHash === candidate.briefHash
+)?.evidence ?? [];
+var allRequiredChecksPassed2 = (policy, checks, expected) => {
+  const reasons = [];
+  for (const name of requiredCheckNames(policy)) {
+    const named = checks.filter((candidate) => candidate.name === name);
+    if (named.length === 0) {
+      reasons.push(`Required check is missing: ${name}`);
+      continue;
+    }
+    const check = expected === void 0 ? named[0] : named.find(
+      (candidate) => candidate.headSha === expected.headSha && (expected.baseSha === void 0 || candidate.baseSha === expected.baseSha) && (expected.briefHash === void 0 || candidate.briefHash === expected.briefHash)
+    );
+    if (check === void 0) {
+      reasons.push(
+        `Required check is stale for the current candidate: ${name}`
+      );
+    } else if (check.status !== "passed") {
+      reasons.push(`Required check ${name} is ${check.status}`);
+    }
+  }
+  return reasons;
+};
+var candidateReasons = (job, candidate, review, requiredAxes) => {
+  const reasons = [];
+  let brief;
+  try {
+    brief = parseWorkBrief(job.brief);
+  } catch {
+    return ["Workflow brief is malformed"];
+  }
+  if (brief.identity.kind !== "executable-issue") {
+    reasons.push("Only executable issues may reach human PR handoff");
+  }
+  if (!isAuthorizationAllowed(brief, job.policy)) {
+    reasons.push("Implementation authorization is not approved");
+  }
+  if (brief.identity.repository !== job.policy.repository) {
+    reasons.push("Workflow policy repository does not match the brief");
+  }
+  if (job.control !== "active") reasons.push(`Workflow job is ${job.control}`);
+  if (!sameRevision(brief.base, candidate.base)) {
+    reasons.push("Candidate base does not match the brief base");
+  }
+  if (review.baseSha !== candidate.base.sha) {
+    reasons.push("Review evidence is bound to a different base revision");
+  }
+  if (review.headSha !== candidate.head.sha) {
+    reasons.push("Review evidence is bound to a different candidate head");
+  }
+  if (review.briefHash !== candidate.briefHash || review.briefHash !== brief.hash) {
+    reasons.push("Review evidence is bound to a different brief revision");
+  }
+  const implementationHead = [...job.phaseResults].reverse().find(
+    (result) => result.phase === "implementation" || result.phase === "repair"
+  )?.head;
+  if (implementationHead !== void 0 && !sameRevision(implementationHead, candidate.head)) {
+    reasons.push("Candidate head does not match the implementation result");
+  }
+  if (review.outcome !== "passed") {
+    reasons.push(`Independent review outcome is ${review.outcome}`);
+  }
+  if (implementationEvidence(job, candidate).length < brief.acceptanceCriteria.length) {
+    reasons.push("Implementation acceptance evidence is missing");
+  }
+  for (const axis of requiredAxes) {
+    if (!review.axes.includes(axis))
+      reasons.push(`Review axis is missing: ${axis}`);
+  }
+  for (const finding of review.findings) {
+    if (isBlockingFinding(finding)) {
+      reasons.push(`Blocking finding remains: ${finding.id}`);
+    }
+  }
+  return reasons;
+};
+var packetFor = (input, brief) => ({
+  sourceIssue: `#${brief.identity.itemId}`,
+  candidate: input.candidate,
+  briefRevision: brief.revision,
+  briefHash: brief.hash,
+  change: brief.problem,
+  risk: brief.risk,
+  acceptanceCriteria: brief.acceptanceCriteria,
+  acceptanceEvidence: implementationEvidence(input.job, input.candidate),
+  checks: input.checks,
+  reviewAxes: input.review.axes,
+  findings: input.review.findings,
+  limitations: [
+    ...brief.exclusions,
+    ...brief.unresolvedQuestions.map((question) => `Unresolved: ${question}`)
+  ]
+});
+var approvalMatches = (candidate, brief, policy, approval) => approval !== void 0 && approval.actor.trim().length > 0 && approval.approvedAt.trim().length > 0 && policy.authorization.allowedActors.includes(approval.actorRole) && approval.baseSha === candidate.base.sha && approval.headSha === candidate.head.sha && approval.briefHash === brief.hash;
+var evaluateHandoffReadiness = (input) => {
+  const brief = parseWorkBrief(input.job.brief);
+  const policy = parseRepositoryPolicy(input.job.policy);
+  const requiredAxes = [
+    .../* @__PURE__ */ new Set([...defaultAxes, ...input.requiredAxes ?? []])
+  ];
+  const reasons = [
+    ...candidateReasons(input.job, input.candidate, input.review, requiredAxes),
+    ...allRequiredChecksPassed2(policy, input.checks, {
+      baseSha: input.candidate.base.sha,
+      headSha: input.candidate.head.sha,
+      briefHash: input.candidate.briefHash
+    })
+  ];
+  const packet = {
+    ...packetFor(input, brief),
+    pullRequest: void 0
+  };
+  const readyForHuman = reasons.length === 0;
+  const protection = input.branchProtection;
+  const freshnessWindowSeconds = input.freshnessWindowSeconds ?? 300;
+  const freshMergeEvidence = Number.isFinite(freshnessWindowSeconds) && freshnessWindowSeconds > 0 && protection?.provider === "github" && isFreshTimestamp(
+    protection.verifiedAt,
+    input.now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
+    freshnessWindowSeconds
+  ) && input.humanApproval !== void 0 && isFreshTimestamp(
+    input.humanApproval.approvedAt,
+    input.now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
+    freshnessWindowSeconds
+  );
+  const mergeReady = readyForHuman && protection?.enforced === true && protection.humanApprovalRequired === true && freshMergeEvidence && approvalMatches(input.candidate, brief, policy, input.humanApproval);
+  if (!readyForHuman) {
+    return {
+      outcome: "blocked",
+      readyForReview: false,
+      reviewRequested: false,
+      readyForHuman: false,
+      mergeReady: false,
+      reasons,
+      packet
+    };
+  }
+  return {
+    outcome: mergeReady ? "merge-ready" : "ready-for-review",
+    readyForReview: true,
+    reviewRequested: false,
+    readyForHuman: true,
+    mergeReady,
+    reasons,
+    packet
+  };
+};
+var prepareHumanHandoff = async (input) => {
+  if (input.readCurrent !== void 0) {
+    let current;
+    try {
+      current = await input.readCurrent();
+    } catch (error) {
+      const brief = parseWorkBrief(input.job.brief);
+      return {
+        outcome: "blocked",
+        readyForReview: false,
+        reviewRequested: false,
+        readyForHuman: false,
+        mergeReady: false,
+        reasons: [
+          `Could not validate the current candidate: ${error instanceof Error ? error.message : String(error)}`
+        ],
+        packet: {
+          ...packetFor(input, brief),
+          pullRequest: `#${input.pullRequestNumber}`
+        }
+      };
+    }
+    if (!sameRevision(current.base, input.candidate.base) || !sameRevision(current.head, input.candidate.head) || current.briefHash !== input.candidate.briefHash) {
+      const brief = parseWorkBrief(input.job.brief);
+      return {
+        outcome: "blocked",
+        readyForReview: false,
+        reviewRequested: false,
+        readyForHuman: false,
+        mergeReady: false,
+        reasons: ["Candidate changed before human handoff"],
+        packet: {
+          ...packetFor(input, brief),
+          pullRequest: `#${input.pullRequestNumber}`
+        }
+      };
+    }
+  }
+  const readiness = evaluateHandoffReadiness(input);
+  const packet = {
+    ...readiness.packet,
+    pullRequest: `#${input.pullRequestNumber}`
+  };
+  let result = { ...readiness, packet };
+  if (result.readyForHuman && input.publisher !== void 0) {
+    try {
+      await input.publisher.requestReview({
+        packet,
+        pullRequestNumber: input.pullRequestNumber
+      });
+      result = {
+        ...result,
+        outcome: "review-requested",
+        reviewRequested: true
+      };
+    } catch (error) {
+      result = {
+        ...result,
+        outcome: "blocked",
+        readyForReview: false,
+        reviewRequested: false,
+        readyForHuman: false,
+        reasons: [
+          `Could not request human review: ${error instanceof Error ? error.message : String(error)}`
+        ]
+      };
+    }
+  }
+  return result;
+};
+var resolveHumanReviewDecision = (input) => {
+  switch (input.decision) {
+    case "approved":
+      return { outcome: "merge-ready", reason: input.reason };
+    case "changes-requested":
+      return {
+        outcome: "repair-needed",
+        reason: input.reason ?? "Human review requested changes"
+      };
+    case "rejected":
+      return {
+        outcome: "rejected",
+        reason: input.reason ?? "Human review rejected the candidate"
+      };
+    case "abandoned":
+      return {
+        outcome: "abandoned",
+        reason: input.reason ?? "Pull request was abandoned"
+      };
+  }
+};
+var processHumanReviewDecision = async (input) => {
+  let current;
+  try {
+    current = await input.readCurrent();
+  } catch (error) {
+    return {
+      outcome: "blocked",
+      reason: `Could not validate the current candidate: ${error instanceof Error ? error.message : String(error)}`,
+      candidate: input.candidate,
+      pullRequestNumber: input.pullRequestNumber
+    };
+  }
+  if (!sameRevision(current.base, input.candidate.base) || !sameRevision(current.head, input.candidate.head) || current.briefHash !== input.candidate.briefHash) {
+    return {
+      outcome: "blocked",
+      reason: "Human review decision is stale for the current candidate",
+      candidate: input.candidate,
+      pullRequestNumber: input.pullRequestNumber
+    };
+  }
+  const decision = resolveHumanReviewDecision(input.decision);
+  if (decision.outcome === "repair-needed") {
+    try {
+      await input.requestRepair({
+        candidate: input.candidate,
+        pullRequestNumber: input.pullRequestNumber,
+        reason: decision.reason ?? "Human review requested changes"
+      });
+    } catch (error) {
+      return {
+        outcome: "blocked",
+        reason: `Could not schedule the requested repair: ${error instanceof Error ? error.message : String(error)}`,
+        candidate: input.candidate,
+        pullRequestNumber: input.pullRequestNumber
+      };
+    }
+  }
+  return {
+    ...decision,
+    candidate: input.candidate,
+    pullRequestNumber: input.pullRequestNumber
+  };
+};
+var mergeProtectedCandidate = async (input) => {
+  const brief = parseWorkBrief(input.job.brief);
+  const policy = parseRepositoryPolicy(input.job.policy);
+  let current;
+  try {
+    current = await input.readCurrent();
+  } catch (error) {
+    return {
+      outcome: "blocked",
+      reason: `Could not validate the current candidate: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  if (!sameRevision(current.base, input.candidate.base) || !sameRevision(current.head, input.candidate.head) || current.briefHash !== input.candidate.briefHash) {
+    return {
+      outcome: "blocked",
+      reason: "current candidate changed before protected merge"
+    };
+  }
+  const freshnessWindowSeconds = input.freshnessWindowSeconds ?? 300;
+  if (!Number.isFinite(freshnessWindowSeconds) || freshnessWindowSeconds <= 0) {
+    return {
+      outcome: "blocked",
+      reason: "Freshness window must be a positive number of seconds"
+    };
+  }
+  let branchProtection;
+  try {
+    branchProtection = await input.readBranchProtection();
+  } catch (error) {
+    return {
+      outcome: "blocked",
+      reason: `Could not verify branch protection: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  const readiness = evaluateHandoffReadiness({
+    ...input,
+    branchProtection
+  });
+  if (!readiness.readyForHuman) {
+    return { outcome: "blocked", reason: readiness.reasons.join("; ") };
+  }
+  if (!branchProtection.enforced) {
+    return {
+      outcome: "blocked",
+      reason: "Branch protection is not proven enforced"
+    };
+  }
+  if (!branchProtection.humanApprovalRequired) {
+    return {
+      outcome: "blocked",
+      reason: "Human approval gate is not configured"
+    };
+  }
+  if (branchProtection.provider !== "github" || !isFreshTimestamp(
+    branchProtection.verifiedAt,
+    input.now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
+    freshnessWindowSeconds
+  )) {
+    return {
+      outcome: "blocked",
+      reason: "Branch protection evidence is not freshly verified"
+    };
+  }
+  if (!isFreshTimestamp(
+    input.humanApproval.approvedAt,
+    input.now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
+    freshnessWindowSeconds
+  )) {
+    return {
+      outcome: "blocked",
+      reason: "Human approval evidence is not fresh"
+    };
+  }
+  if (!approvalMatches(input.candidate, brief, policy, input.humanApproval)) {
+    return {
+      outcome: "blocked",
+      reason: "Human approval does not match the exact candidate"
+    };
+  }
+  try {
+    const merged = await input.transport.mergeProtected({
+      pullRequestNumber: input.pullRequestNumber,
+      headSha: input.candidate.head.sha,
+      baseBranch: policy.baseBranch
+    });
+    return { outcome: "merged", mergedSha: merged.mergedSha };
+  } catch (error) {
+    return {
+      outcome: "blocked",
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+};
+var completeSourceIssue = (input) => {
+  const policy = parseRepositoryPolicy(input.policy);
+  if (input.mergedSha.trim().length === 0) {
+    return {
+      outcome: "open",
+      reason: "Merged revision is missing",
+      mergedSha: input.mergedSha,
+      checks: input.checks
+    };
+  }
+  if (policy.issueClosure !== "merge-and-ci") {
+    return {
+      outcome: "open",
+      reason: "Source issue remains open until release verification",
+      mergedSha: input.mergedSha,
+      checks: input.checks
+    };
+  }
+  const checkReasons = allRequiredChecksPassed2(policy, input.checks, {
+    headSha: input.mergedSha
+  });
+  if (checkReasons.length > 0) {
+    return {
+      outcome: "open",
+      reason: checkReasons.join("; "),
+      mergedSha: input.mergedSha,
+      checks: input.checks
+    };
+  }
+  return {
+    outcome: "completed",
+    mergedSha: input.mergedSha,
+    checks: input.checks
+  };
+};
+var closeSourceIssue = async (input) => {
+  const completion = completeSourceIssue(input);
+  if (completion.outcome === "open") {
+    return { ...completion, closed: false };
+  }
+  try {
+    await input.closer.closeIssue({
+      issueNumber: input.sourceIssueNumber,
+      mergedSha: input.mergedSha,
+      checks: input.checks
+    });
+    return { ...completion, closed: true };
+  } catch (error) {
+    return {
+      ...completion,
+      outcome: "open",
+      closed: false,
+      reason: `Could not close source issue: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+};
+
+// src/workflow/phase-storage.ts
+var PostgresWorkflowPhaseRecordStore = class {
+  client;
+  constructor(options) {
+    this.client = options.client;
+  }
+  async get(kind, key) {
+    const result = await this.client.query(
+      `SELECT record, schema_version
+       FROM shipyard_workflow_phase_records
+       WHERE namespace = $1 AND record_key = $2`,
+      [kind, encodeURIComponent(key)]
+    );
+    const row = result.rows[0];
+    if (row === void 0) return void 0;
+    if (Number(row.schema_version) !== 1) {
+      throw new Error(
+        `Unsupported ${kind} record schema version: ${String(row.schema_version)}`
+      );
+    }
+    if (typeof row.record === "string")
+      return JSON.parse(row.record);
+    return row.record;
+  }
+  async save(kind, key, record, updatedAt) {
+    await this.client.query(
+      `INSERT INTO shipyard_workflow_phase_records
+         (namespace, record_key, schema_version, record, updated_at)
+       VALUES ($1, $2, 1, $3::jsonb, $4::timestamptz)
+       ON CONFLICT (namespace, record_key) DO UPDATE SET
+         schema_version = EXCLUDED.schema_version,
+         record = EXCLUDED.record,
+         updated_at = EXCLUDED.updated_at`,
+      [kind, encodeURIComponent(key), JSON.stringify(record), updatedAt]
+    );
+  }
+  async compareAndSaveTriage(key, expectedRevision, record, updatedAt) {
+    const encodedKey = encodeURIComponent(key);
+    const result = expectedRevision === void 0 ? await this.client.query(
+      `INSERT INTO shipyard_workflow_phase_records
+               (namespace, record_key, schema_version, record, updated_at)
+             VALUES ('triage', $1, 1, $2::jsonb, $3::timestamptz)
+             ON CONFLICT (namespace, record_key) DO NOTHING
+             RETURNING record_key`,
+      [encodedKey, JSON.stringify(record), updatedAt]
+    ) : await this.client.query(
+      `UPDATE shipyard_workflow_phase_records
+             SET schema_version = 1, record = $3::jsonb, updated_at = $4::timestamptz
+             WHERE namespace = 'triage'
+               AND record_key = $1
+               AND record->>'revision' = $2
+             RETURNING record_key`,
+      [
+        encodedKey,
+        String(expectedRevision),
+        JSON.stringify(record),
+        updatedAt
+      ]
+    );
+    return result.rows.length > 0;
+  }
+};
+var nonEmpty = (value, path) => {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${path} must be a non-empty string`);
+  }
+  return value.trim();
+};
+var optionalNonEmpty = (value, path) => value === void 0 ? void 0 : nonEmpty(value, path);
+var isCategory = (value) => typeof value === "string" && [
+  "bug",
+  "enhancement",
+  "support",
+  "duplicate",
+  "sensitive",
+  "non-actionable"
+].includes(value);
+var isRisk = (value) => typeof value === "string" && ["low", "medium", "high", "critical"].includes(value);
+var stringArray2 = (value, path) => {
+  if (!Array.isArray(value)) throw new Error(`${path} must be an array`);
+  return value.map((entry, index) => nonEmpty(entry, `${path}[${index}]`));
+};
+var sha2562 = (value) => createHash("sha256").update(value).digest("hex");
+var sourceKind = (source) => source.kind ?? "executable-issue";
+var sourceKey = (source) => [source.repository, source.itemId, sourceKind(source)].join("\0");
+var sourceFingerprint = (source) => sha2562(
+  JSON.stringify({
+    provider: source.provider,
+    repository: source.repository,
+    itemId: source.itemId,
+    title: source.title,
+    body: source.body,
+    author: source.author ?? "",
+    url: source.url ?? "",
+    updatedAt: source.updatedAt,
+    kind: sourceKind(source),
+    labels: [...source.labels ?? []].sort()
+  })
+);
+var sourceTimestampOrder = (candidateUpdatedAt, storedUpdatedAt) => {
+  const candidateTime = Date.parse(candidateUpdatedAt);
+  const storedTime = Date.parse(storedUpdatedAt);
+  if (!Number.isFinite(candidateTime) || !Number.isFinite(storedTime)) {
+    return "unknown";
+  }
+  return candidateTime < storedTime ? "older" : candidateTime > storedTime ? "newer" : "same";
+};
+var storedObject = (value, path) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${path} must be an object`);
+  }
+  return value;
+};
+var parseStoredSource = (value) => {
+  const source = storedObject(value, "triage.source");
+  const provider = source.provider;
+  if (provider !== "github" && provider !== "slack" && provider !== "manual") {
+    throw new Error("triage.source.provider is invalid");
+  }
+  const allowedKinds = [
+    "planning-spec",
+    "executable-issue",
+    "pr-repair"
+  ];
+  const kind = source.kind ?? "executable-issue";
+  if (typeof kind !== "string" || !allowedKinds.includes(kind)) {
+    throw new Error("triage.source.kind is invalid");
+  }
+  if (typeof source.body !== "string") {
+    throw new Error("triage.source.body must be a string");
+  }
+  if (source.labels !== void 0 && !Array.isArray(source.labels)) {
+    throw new Error("triage.source.labels must be an array");
+  }
+  return normalizeSource({
+    provider,
+    repository: nonEmpty(source.repository, "triage.source.repository"),
+    itemId: nonEmpty(source.itemId, "triage.source.itemId"),
+    title: nonEmpty(source.title, "triage.source.title"),
+    body: source.body,
+    author: optionalNonEmpty(source.author, "triage.source.author"),
+    url: optionalNonEmpty(source.url, "triage.source.url"),
+    updatedAt: nonEmpty(source.updatedAt, "triage.source.updatedAt"),
+    kind,
+    labels: stringArray2(source.labels ?? [], "triage.source.labels")
+  });
+};
+var parseClarificationReply = (value, path) => {
+  const reply = storedObject(value, path);
+  if (typeof reply.body !== "string") {
+    throw new Error(`${path}.body must be a string`);
+  }
+  return {
+    id: nonEmpty(reply.id, `${path}.id`),
+    body: reply.body,
+    author: optionalNonEmpty(reply.author, `${path}.author`),
+    updatedAt: nonEmpty(reply.updatedAt, `${path}.updatedAt`)
+  };
+};
+var normalizeClarificationReply = (reply) => parseClarificationReply(reply, "clarificationReply");
+var parseTriageRecord = (value) => {
+  const record = storedObject(value, "triage record");
+  const source = parseStoredSource(record.source);
+  const assessment = normalizeAssessment(record.assessment);
+  const outcome = record.outcome;
+  const outcomes = [
+    "completed",
+    "needs-info",
+    "duplicate",
+    "sensitive",
+    "non-actionable",
+    "blocked",
+    "failed"
+  ];
+  if (typeof outcome !== "string" || !outcomes.includes(outcome)) {
+    throw new Error("triage.outcome is invalid");
+  }
+  if (!isCategory(record.category))
+    throw new Error("triage.category is invalid");
+  const revision = record.revision;
+  if (typeof revision !== "number" || !Number.isSafeInteger(revision) || revision < 1) {
+    throw new Error("triage.revision must be a positive integer");
+  }
+  const parsedBrief = record.brief === void 0 ? void 0 : parseWorkBrief(record.brief);
+  const clarificationIds = stringArray2(
+    record.clarificationIds,
+    "triage.clarificationIds"
+  );
+  const pendingClarificationReplies = record.pendingClarificationReplies === void 0 ? [] : (() => {
+    if (!Array.isArray(record.pendingClarificationReplies)) {
+      throw new Error(
+        "triage.pendingClarificationReplies must be an array"
+      );
+    }
+    return record.pendingClarificationReplies.map(
+      (reply, index) => parseClarificationReply(
+        reply,
+        `triage.pendingClarificationReplies[${index}]`
+      )
+    );
+  })();
+  const sourceConflict = record.sourceConflict === void 0 ? void 0 : (() => {
+    const conflict = storedObject(
+      record.sourceConflict,
+      "triage.sourceConflict"
+    );
+    const fingerprint = nonEmpty(
+      conflict.fingerprint,
+      "triage.sourceConflict.fingerprint"
+    );
+    if (!/^[0-9a-f]{64}$/.test(fingerprint)) {
+      throw new Error("triage.sourceConflict.fingerprint is invalid");
+    }
+    return {
+      fingerprint,
+      updatedAt: nonEmpty(
+        conflict.updatedAt,
+        "triage.sourceConflict.updatedAt"
+      )
+    };
+  })();
+  const pendingIds = pendingClarificationReplies.map(({ id }) => id);
+  if (new Set(pendingIds).size !== pendingIds.length || pendingIds.some((id) => clarificationIds.includes(id))) {
+    throw new Error("Stored triage clarification replies are not unique");
+  }
+  const parsed = {
+    id: nonEmpty(record.id, "triage.id"),
+    sourceKey: nonEmpty(record.sourceKey, "triage.sourceKey"),
+    source,
+    sourceUpdatedAt: nonEmpty(record.sourceUpdatedAt, "triage.sourceUpdatedAt"),
+    sourceFingerprint: nonEmpty(
+      record.sourceFingerprint,
+      "triage.sourceFingerprint"
+    ),
+    revision,
+    category: record.category,
+    outcome,
+    assessment,
+    brief: parsedBrief,
+    questions: stringArray2(record.questions, "triage.questions"),
+    clarificationIds,
+    ...pendingClarificationReplies.length === 0 ? {} : { pendingClarificationReplies },
+    ...sourceConflict === void 0 ? {} : { sourceConflict },
+    duplicateOf: optionalNonEmpty(record.duplicateOf, "triage.duplicateOf"),
+    publicMessage: nonEmpty(record.publicMessage, "triage.publicMessage"),
+    createdAt: nonEmpty(record.createdAt, "triage.createdAt"),
+    updatedAt: nonEmpty(record.updatedAt, "triage.updatedAt")
+  };
+  if (parsed.sourceKey !== sourceKey(source)) {
+    throw new Error("Stored triage source key does not match its source");
+  }
+  if (parsed.sourceUpdatedAt !== source.updatedAt) {
+    throw new Error("Stored triage source timestamp does not match its source");
+  }
+  if (parsed.sourceFingerprint !== sourceFingerprint(source)) {
+    throw new Error("Stored triage fingerprint does not match its source");
+  }
+  if (parsed.category !== assessment.category) {
+    throw new Error("Stored triage category does not match its assessment");
+  }
+  if (sourceConflict !== void 0 && (parsed.outcome !== "blocked" || parsedBrief !== void 0 || sourceConflict.fingerprint === parsed.sourceFingerprint)) {
+    throw new Error("Stored triage source conflict is inconsistent");
+  }
+  if (parsedBrief !== void 0 && (parsedBrief.revision !== revision || parsedBrief.identity.repository !== source.repository || parsedBrief.identity.itemId !== source.itemId || parsedBrief.identity.kind !== sourceKind(source))) {
+    throw new Error("Stored triage brief does not match its source revision");
+  }
+  return parsed;
+};
+var normalizeSource = (source) => ({
+  ...source,
+  repository: nonEmpty(source.repository, "source.repository"),
+  itemId: nonEmpty(source.itemId, "source.itemId"),
+  title: nonEmpty(source.title, "source.title"),
+  body: typeof source.body === "string" ? source.body : "",
+  author: optionalNonEmpty(source.author, "source.author"),
+  url: optionalNonEmpty(source.url, "source.url"),
+  updatedAt: nonEmpty(source.updatedAt, "source.updatedAt"),
+  kind: sourceKind(source),
+  labels: [...source.labels ?? []].map(
+    (label, index) => nonEmpty(label, `source.labels[${index}]`)
+  )
+});
+var normalizeAssessment = (value) => {
+  const assessment = storedObject(value, "assessment");
+  if (!isCategory(assessment.category))
+    throw new Error("assessment.category is invalid");
+  if (!isRisk(assessment.risk)) throw new Error("assessment.risk is invalid");
+  if (typeof assessment.requirementsConfirmed !== "boolean") {
+    throw new Error("assessment.requirementsConfirmed must be a boolean");
+  }
+  const duplicateOf = optionalNonEmpty(
+    assessment.duplicateOf,
+    "assessment.duplicateOf"
+  );
+  const sensitiveReason = optionalNonEmpty(
+    assessment.sensitiveReason,
+    "assessment.sensitiveReason"
+  );
+  return {
+    category: assessment.category,
+    evidence: stringArray2(assessment.evidence, "assessment.evidence"),
+    relevantFiles: stringArray2(
+      assessment.relevantFiles,
+      "assessment.relevantFiles"
+    ),
+    acceptanceCriteria: stringArray2(
+      assessment.acceptanceCriteria,
+      "assessment.acceptanceCriteria"
+    ),
+    exclusions: stringArray2(assessment.exclusions, "assessment.exclusions"),
+    risk: assessment.risk,
+    verification: stringArray2(
+      assessment.verification,
+      "assessment.verification"
+    ),
+    unresolvedQuestions: stringArray2(
+      assessment.unresolvedQuestions,
+      "assessment.unresolvedQuestions"
+    ),
+    requirementsConfirmed: assessment.requirementsConfirmed,
+    duplicateOf,
+    sensitiveReason
+  };
+};
+
+// src/workflow/triage/reconciliation.ts
+var reconcileTriageSource = (input) => {
+  const { source, sourceFingerprint: sourceFingerprint2, existing, incomingReply } = input;
+  const timestampOrder = existing === void 0 ? "newer" : sourceTimestampOrder(source.updatedAt, existing.sourceUpdatedAt);
+  const sourceChanged = existing !== void 0 && existing.sourceFingerprint !== sourceFingerprint2;
+  const sourceTimestampAmbiguous = sourceChanged && timestampOrder !== "older" && timestampOrder !== "newer";
+  const replyAlreadyApplied = incomingReply !== void 0 && (existing?.clarificationIds.includes(incomingReply.id) ?? false);
+  const storedReplies = existing?.pendingClarificationReplies ?? [];
+  const pendingIds = new Set(storedReplies.map(({ id }) => id));
+  const newReply = incomingReply !== void 0 && !replyAlreadyApplied && !pendingIds.has(incomingReply.id) ? incomingReply : void 0;
+  const pendingReplies = newReply === void 0 ? [...storedReplies] : [...storedReplies, newReply];
+  const priorConflictIsUnresolved = existing?.sourceConflict !== void 0 && timestampOrder !== "newer";
+  if (existing !== void 0 && (sourceTimestampAmbiguous || priorConflictIsUnresolved)) {
+    const sourceConflict = sourceTimestampAmbiguous ? { fingerprint: sourceFingerprint2, updatedAt: source.updatedAt } : existing.sourceConflict;
+    if (existing.sourceConflict?.fingerprint === sourceConflict.fingerprint && existing.outcome === "blocked" && existing.brief === void 0 && newReply === void 0) {
+      return { kind: "unchanged", record: existing };
+    }
+    return {
+      kind: "source-conflict",
+      existing,
+      sourceConflict,
+      pendingReplies
+    };
+  }
+  const storedSnapshotWins = existing !== void 0 && (existing.sourceFingerprint === sourceFingerprint2 || timestampOrder !== "newer");
+  const currentSource = storedSnapshotWins ? existing.source : source;
+  const currentFingerprint = storedSnapshotWins ? existing.sourceFingerprint : sourceFingerprint2;
+  if (existing !== void 0 && pendingReplies.length === 0 && existing.sourceFingerprint === currentFingerprint) {
+    return { kind: "unchanged", record: existing };
+  }
+  return {
+    kind: "investigate",
+    source: currentSource,
+    sourceFingerprint: currentFingerprint,
+    pendingReplies
+  };
+};
+
+// src/workflow/triage/index.ts
+var InMemoryTriageStore = class {
+  records = /* @__PURE__ */ new Map();
+  get(sourceKey2) {
+    const record = this.records.get(sourceKey2);
+    return record === void 0 ? void 0 : clone(record);
+  }
+  compareAndSave(record, expectedRevision) {
+    const current = this.records.get(record.sourceKey);
+    if (current?.revision !== expectedRevision) return false;
+    this.records.set(record.sourceKey, clone(record));
+    return true;
+  }
+};
+var PostgresTriageStore = class {
+  records;
+  constructor(options) {
+    this.records = new PostgresWorkflowPhaseRecordStore(options);
+  }
+  async get(sourceKey2) {
+    const record = await this.records.get("triage", sourceKey2);
+    return record === void 0 ? void 0 : parseTriageRecord(record);
+  }
+  compareAndSave(record, expectedRevision) {
+    return this.records.compareAndSaveTriage(
+      record.sourceKey,
+      expectedRevision,
+      record,
+      record.updatedAt
+    );
+  }
+};
+var defaultNow = () => (/* @__PURE__ */ new Date()).toISOString();
+var clone = (value) => JSON.parse(JSON.stringify(value));
+var MAX_TRIAGE_WRITE_CONFLICT_RETRIES = 5;
+var safeDuplicateId = (value) => {
+  if (value === void 0 || !/^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,79}$/.test(value)) {
+    return void 0;
+  }
+  return value;
+};
+var defaultInvestigator = {
+  async investigate({ source }) {
+    const text = `${source.title}
+${source.body}`.toLowerCase();
+    const labels = new Set(
+      (source.labels ?? []).map((label) => label.toLowerCase())
+    );
+    const duplicateMatch = text.match(
+      /(?:duplicate|dupe)(?: of|:|#)\s*([\w./:-]+)/i
+    );
+    const category = labels.has("sensitive") || /\b(secret|token|password|credential|security report)\b/.test(text) ? "sensitive" : labels.has("duplicate") || duplicateMatch !== null ? "duplicate" : labels.has("support") || /\?|\b(how do i|support|question)\b/.test(text) ? "support" : labels.has("bug") || /\b(bug|fix|error|crash|broken|fail(?:ed|ure)?)\b/.test(text) ? "bug" : "enhancement";
+    const highRisk = /\b(auth|billing|payment|migration|destructive|security)\b/.test(text);
+    const hasExplicitRequirements = /\b(acceptance|expected|should|must|given|when|then)\b/.test(text) && source.body.trim().length > 0;
+    return {
+      category,
+      evidence: [
+        "Classification derived from the submitted title, body, and labels."
+      ],
+      relevantFiles: [],
+      acceptanceCriteria: hasExplicitRequirements ? ["Implement only the explicitly described behavior."] : [],
+      exclusions: [
+        "Do not expand scope beyond the retained source and confirmed answers."
+      ],
+      risk: highRisk ? "high" : "low",
+      verification: [],
+      unresolvedQuestions: hasExplicitRequirements ? [] : [
+        "What observable behavior should change, and how will it be accepted?"
+      ],
+      requirementsConfirmed: hasExplicitRequirements,
+      duplicateOf: safeDuplicateId(duplicateMatch?.[1])
+    };
+  }
+};
+var investigate = (investigator, request) => typeof investigator === "function" ? investigator(request) : investigator.investigate(request);
+var canAutoAuthorize = (source, assessment, policy) => sourceKind(source) === "executable-issue" && !policy.authorization.required && policy.authorization.allowedActors.includes("policy") && policy.authorization.autoStartRisk.includes(assessment.risk) && assessment.requirementsConfirmed && assessment.unresolvedQuestions.length === 0 && assessment.acceptanceCriteria.length > 0 && assessment.category !== "support" && assessment.category !== "duplicate" && assessment.category !== "sensitive" && assessment.category !== "non-actionable";
+var outcomeForAssessment = (source, assessment) => {
+  const category = assessment.category;
+  const questions = assessment.unresolvedQuestions;
+  if (sourceKind(source) !== "executable-issue") return "blocked";
+  if (category === "duplicate") return "duplicate";
+  if (category === "sensitive") return "sensitive";
+  if (category === "non-actionable") return "non-actionable";
+  return !assessment.requirementsConfirmed || questions.length > 0 || assessment.acceptanceCriteria.length === 0 ? "needs-info" : "completed";
+};
+var sourceConflictMessage = (hasPendingReplies) => hasPendingReplies ? "Triage is blocked because the source update cannot be ordered against the saved revision; the clarification reply is saved and will be applied after the source is refreshed." : "Triage is blocked because the source update cannot be ordered against the saved revision; refresh the source before triage can continue.";
+var publicMessage = (outcome, category, questions, duplicateId) => {
+  switch (outcome) {
+    case "needs-info":
+      return `Triage needs clarification (${questions.length} question${questions.length === 1 ? "" : "s"}); the work item remains paused.`;
+    case "duplicate":
+      return duplicateId === void 0 ? "Triage routed this report as a duplicate for maintainer review." : `Triage routed this report as a duplicate of #${duplicateId}.`;
+    case "sensitive":
+      return "Triage routed this report to the private security channel; sensitive details are not reproduced here.";
+    case "non-actionable":
+      return "Triage routed this report for maintainer disposition.";
+    case "blocked":
+      return "Triage recorded the work item but ordinary implementation dispatch is blocked for this item type.";
+    case "failed":
+      return "Triage could not complete; a maintainer must inspect the failure without relying on source text in public output.";
+    case "completed":
+      return category === "support" ? "Triage recorded this support request for a maintainer response." : "Triage completed; implementation authorization remains a separate policy decision.";
+  }
+};
+var makeBrief = (source, assessment, policy, base, revision, createdAt) => {
+  const originalBody = source.body.trim().length > 0 ? source.body : "(empty source body)";
+  const authorization = canAutoAuthorize(source, assessment, policy) ? {
+    status: "approved",
+    actor: "policy",
+    actorRole: "policy",
+    approvedAt: createdAt
+  } : { status: "pending" };
+  return createWorkBrief({
+    id: `${source.repository}:${sourceKind(source)}:${source.itemId}`,
+    revision,
+    identity: {
+      repository: source.repository,
+      itemId: source.itemId,
+      kind: sourceKind(source)
+    },
+    source: {
+      provider: source.provider,
+      repository: source.repository,
+      itemId: source.itemId,
+      url: source.url,
+      originalBody,
+      author: source.author
+    },
+    problem: source.title,
+    evidence: assessment.evidence,
+    acceptanceCriteria: assessment.acceptanceCriteria,
+    exclusions: assessment.exclusions,
+    risk: assessment.risk,
+    verification: {
+      checks: assessment.verification,
+      artifacts: assessment.relevantFiles
+    },
+    unresolvedQuestions: assessment.unresolvedQuestions,
+    authorization,
+    base,
+    policyRevision: policy.revision,
+    skillRevision: policy.worker.skillRevision,
+    createdAt
+  });
+};
+var resultFromRecord = (record, policy) => ({
+  outcome: record.outcome,
+  category: record.category,
+  brief: record.brief,
+  questions: record.questions,
+  publicMessage: record.publicMessage,
+  record,
+  implementationEligible: record.outcome === "completed" && record.category !== "support" && record.brief?.identity.kind === "executable-issue" && record.brief !== void 0 && record.brief.policyRevision === policy.revision && isAuthorizationAllowed(record.brief, policy)
+});
+var runTriage = async ({
+  source: rawSource,
+  policy,
+  base,
+  store,
+  investigator = defaultInvestigator,
+  clarificationReply,
+  now = defaultNow
+}) => {
+  const source = normalizeSource(rawSource);
+  if (source.repository !== policy.repository) {
+    throw new Error("source.repository must match policy.repository");
+  }
+  const incomingReply = clarificationReply === void 0 ? void 0 : normalizeClarificationReply(clarificationReply);
+  const key = sourceKey(source);
+  const fingerprint = sourceFingerprint(source);
+  for (let conflictAttempt = 0; conflictAttempt <= MAX_TRIAGE_WRITE_CONFLICT_RETRIES; conflictAttempt += 1) {
+    const existing = await store.get(key);
+    const reconciliation = reconcileTriageSource({
+      source,
+      sourceFingerprint: fingerprint,
+      existing,
+      incomingReply
+    });
+    if (reconciliation.kind === "unchanged") {
+      return resultFromRecord(reconciliation.record, policy);
+    }
+    if (reconciliation.kind === "source-conflict") {
+      const { existing: existing2, sourceConflict, pendingReplies } = reconciliation;
+      const timestamp2 = now();
+      const record2 = {
+        id: existing2.id,
+        sourceKey: key,
+        source: existing2.source,
+        sourceUpdatedAt: existing2.sourceUpdatedAt,
+        sourceFingerprint: existing2.sourceFingerprint,
+        revision: existing2.revision + 1,
+        category: existing2.category,
+        outcome: "blocked",
+        assessment: existing2.assessment,
+        questions: [],
+        clarificationIds: existing2.clarificationIds,
+        ...pendingReplies.length === 0 ? {} : { pendingClarificationReplies: pendingReplies },
+        sourceConflict,
+        publicMessage: sourceConflictMessage(pendingReplies.length > 0),
+        duplicateOf: existing2.duplicateOf,
+        createdAt: existing2.createdAt,
+        updatedAt: timestamp2
+      };
+      if (await store.compareAndSave(record2, existing2.revision)) {
+        return resultFromRecord(record2, policy);
+      }
+      continue;
+    }
+    const {
+      source: currentSource,
+      sourceFingerprint: currentFingerprint,
+      pendingReplies: currentPendingReplies
+    } = reconciliation;
+    const timestamp = now();
+    let assessment;
+    try {
+      let previous = existing;
+      if (currentPendingReplies.length === 0) {
+        assessment = normalizeAssessment(
+          await investigate(investigator, {
+            source: currentSource,
+            policy,
+            base,
+            previous
+          })
+        );
+      } else {
+        for (const [index, reply] of currentPendingReplies.entries()) {
+          assessment = normalizeAssessment(
+            await investigate(investigator, {
+              source: currentSource,
+              policy,
+              base,
+              previous,
+              clarificationReply: reply
+            })
+          );
+          const processedReplyIds = currentPendingReplies.slice(0, index + 1).map(({ id }) => id);
+          const remainingReplies = currentPendingReplies.slice(index + 1);
+          const previousOutcome = outcomeForAssessment(
+            currentSource,
+            assessment
+          );
+          const previousCategory = assessment.category;
+          const previousDuplicateId = safeDuplicateId(assessment.duplicateOf);
+          previous = {
+            id: existing?.id ?? `${currentSource.repository}:${sourceKind(currentSource)}:${currentSource.itemId}`,
+            sourceKey: key,
+            source: currentSource,
+            sourceUpdatedAt: currentSource.updatedAt,
+            sourceFingerprint: currentFingerprint,
+            revision: existing?.revision ?? 1,
+            category: previousCategory,
+            outcome: previousOutcome,
+            assessment,
+            questions: assessment.unresolvedQuestions,
+            clarificationIds: [
+              ...existing?.clarificationIds ?? [],
+              ...processedReplyIds
+            ],
+            ...remainingReplies.length === 0 ? {} : { pendingClarificationReplies: remainingReplies },
+            duplicateOf: previousDuplicateId,
+            publicMessage: publicMessage(
+              previousOutcome,
+              previousCategory,
+              assessment.unresolvedQuestions,
+              previousDuplicateId
+            ),
+            createdAt: existing?.createdAt ?? timestamp,
+            updatedAt: timestamp
+          };
+        }
+      }
+    } catch {
+      const failedAssessment = {
+        category: "non-actionable",
+        evidence: [
+          "The investigator did not return a usable structured assessment."
+        ],
+        relevantFiles: [],
+        acceptanceCriteria: [],
+        exclusions: [
+          "No implementation may start from an incomplete assessment."
+        ],
+        risk: "high",
+        verification: [],
+        unresolvedQuestions: [],
+        requirementsConfirmed: false
+      };
+      const record2 = {
+        id: existing?.id ?? `${currentSource.repository}:${sourceKind(currentSource)}:${currentSource.itemId}`,
+        sourceKey: key,
+        source: currentSource,
+        sourceUpdatedAt: currentSource.updatedAt,
+        sourceFingerprint: currentFingerprint,
+        revision: existing === void 0 ? 1 : existing.revision + 1,
+        category: failedAssessment.category,
+        outcome: "failed",
+        assessment: failedAssessment,
+        questions: [],
+        clarificationIds: existing?.clarificationIds ?? [],
+        ...currentPendingReplies.length === 0 ? {} : { pendingClarificationReplies: currentPendingReplies },
+        publicMessage: publicMessage("failed", failedAssessment.category, []),
+        createdAt: existing?.createdAt ?? timestamp,
+        updatedAt: timestamp
+      };
+      if (await store.compareAndSave(record2, existing?.revision)) {
+        return resultFromRecord(record2, policy);
+      }
+      continue;
+    }
+    if (assessment === void 0) {
+      throw new Error("Triage investigator returned no assessment");
+    }
+    const questions = assessment.unresolvedQuestions;
+    const category = assessment.category;
+    const duplicateId = safeDuplicateId(assessment.duplicateOf);
+    const outcome = outcomeForAssessment(currentSource, assessment);
+    const nextRevision = existing === void 0 ? 1 : existing.revision + 1;
+    const brief = makeBrief(
+      currentSource,
+      assessment,
+      policy,
+      base,
+      nextRevision,
+      existing?.createdAt ?? timestamp
+    );
+    const record = {
+      id: existing?.id ?? brief.id,
+      sourceKey: key,
+      source: currentSource,
+      sourceUpdatedAt: currentSource.updatedAt,
+      sourceFingerprint: currentFingerprint,
+      revision: nextRevision,
+      category,
+      outcome,
+      assessment,
+      brief,
+      questions,
+      clarificationIds: [
+        ...existing?.clarificationIds ?? [],
+        ...currentPendingReplies.map(({ id }) => id)
+      ],
+      duplicateOf: duplicateId,
+      publicMessage: publicMessage(outcome, category, questions, duplicateId),
+      createdAt: existing?.createdAt ?? timestamp,
+      updatedAt: timestamp
+    };
+    if (await store.compareAndSave(record, existing?.revision)) {
+      return resultFromRecord(record, policy);
+    }
+  }
+  throw new Error(
+    `Triage record for ${source.repository} item ${source.itemId} changed during ${MAX_TRIAGE_WRITE_CONFLICT_RETRIES + 1} consecutive updates`
+  );
+};
+
+export { ContractValidationError, InMemoryTriageStore, PostgresTriageStore, PostgresWorkflowPhaseRecordStore, WORKFLOW_CONTRACT_VERSION, closeSourceIssue, completeSourceIssue, createAssignment, createRepositoryPolicy, createWorkBrief, deepFreeze, defaultInvestigator, evaluateHandoffReadiness, isAuthorizationAllowed, isBlockingFinding, mergeProtectedCandidate, parseCheckEvidence, parsePhaseResult, parseRepositoryPolicy, parseWorkBrief, prepareHumanHandoff, processHumanReviewDecision, requireTransition, requiredCheckNames, resolveAgentSelection, resolveHumanReviewDecision, runTriage, sameRevision, sameWorkIdentity };
+//# sourceMappingURL=chunk-NQRFVKCU.js.map
+//# sourceMappingURL=chunk-NQRFVKCU.js.map