@storewright/cli 0.14.0

package/lib/internal/operation-ledger.mjs

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile, appendFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+const allowedOperationStatuses = new Set([
+  "prepared",
+  "dispatched",
+  "succeeded",
+  "failed",
+  "indeterminate",
+  "reconciled",
+  "compensated"
+]);
+
+function stableJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function sha256Text(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+function ledgerPath({ runDir, stageId, attemptId }) {
+  return join(runDir, "stages", stageId, "attempts", attemptId, "work", "external-operations.jsonl");
+}
+
+function approvalPath({ runDir, approvalId }) {
+  return join(runDir, "approvals", `${approvalId}.json`);
+}
+
+function includesAll(values, required = []) {
+  const valueSet = new Set(values ?? []);
+  return required.every((value) => valueSet.has(value));
+}
+
+function isInsideDirectory(parentDir, childPath) {
+  const relativePath = relative(resolve(parentDir), resolve(childPath));
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+export async function createApprovalGrant({
+  runDir,
+  approvalId,
+  runId,
+  actionId,
+  impactClass,
+  approvalRequirement,
+  approvedBy,
+  source
+}) {
+  const artifact = {
+    schemaVersion: "1.0.0",
+    approvalId,
+    runId,
+    actionId,
+    impactClass,
+    approvalRequirement,
+    approvedBy,
+    source,
+    grantedAt: new Date().toISOString()
+  };
+  const path = approvalPath({ runDir, approvalId });
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, stableJson(artifact));
+  return { path, artifact, sha256: sha256Text(JSON.stringify(artifact)) };
+}
+
+export async function validateApprovalForAction({
+  runDir,
+  actionRegistry,
+  actionId,
+  approvalGrantPath
+}) {
+  const errors = [];
+  const action = actionRegistry.actions?.[actionId];
+  if (!action) {
+    return { ok: false, errors: [`Unknown action: ${actionId}`] };
+  }
+  if (action.approvalRequirement !== "explicit-user") {
+    return { ok: true, errors };
+  }
+  if (!approvalGrantPath) {
+    return { ok: false, errors: [`${actionId} requires explicit-user approval`] };
+  }
+  if (!isInsideDirectory(join(runDir, "approvals"), approvalGrantPath)) {
+    return { ok: false, errors: ["approval grant must live under the run approvals directory"] };
+  }
+
+  const grant = JSON.parse(await readFile(approvalGrantPath, "utf8"));
+  if (grant.actionId !== actionId) errors.push("approval grant actionId does not match action");
+  if (grant.impactClass !== action.impactClass) errors.push("approval grant impactClass does not match action");
+  if (grant.approvalRequirement !== "explicit-user") errors.push("approval grant must be explicit-user");
+  if (!grant.approvedBy) errors.push("approval grant approvedBy is required");
+  return { ok: errors.length === 0, errors };
+}
+
+function operationIdFromKey(operationKey) {
+  return createHash("sha256").update(operationKey).digest("hex").slice(0, 20);
+}
+
+export async function prepareExternalOperation({
+  runDir,
+  stageId,
+  attemptId,
+  envelope,
+  actionRegistry,
+  actionId,
+  launchEnvelopeSha256,
+  grantedScopes = [],
+  approvalGrantPath = null,
+  operationKey,
+  targetStore,
+  apiVersion,
+  requestFingerprint,
+  naturalResourceKey,
+  providerIdempotencySupported,
+  resourceType
+}) {
+  const action = actionRegistry.actions?.[actionId];
+  if (!action) {
+    throw new Error(`Unknown action: ${actionId}`);
+  }
+  if (!envelope.effectiveAllowedActions?.includes(actionId)) {
+    throw new Error(`${actionId} is not present in effectiveAllowedActions`);
+  }
+  if (launchEnvelopeSha256 !== envelope.launchEnvelopeSha256) {
+    throw new Error("launchEnvelopeSha256 does not match envelope");
+  }
+  if (!includesAll(grantedScopes, action.requiredScopes)) {
+    throw new Error(`${actionId} missing required scopes`);
+  }
+  const approval = await validateApprovalForAction({ runDir, actionRegistry, actionId, approvalGrantPath });
+  if (!approval.ok) {
+    throw new Error(approval.errors.join("\n"));
+  }
+
+  const operation = {
+    schemaVersion: "1.0.0",
+    operationId: operationIdFromKey(operationKey),
+    operationKey,
+    actionId,
+    launchEnvelopeSha256,
+    targetStore,
+    apiVersion,
+    requestFingerprint,
+    naturalResourceKey,
+    providerIdempotencySupported,
+    resourceType,
+    resourceId: null,
+    resourceOwnership: "created-by-this-run",
+    status: "prepared",
+    reconcileStrategy: "lookup-by-natural-resource-key-and-compare",
+    compensation: null,
+    recordedAt: new Date().toISOString()
+  };
+
+  const path = ledgerPath({ runDir, stageId, attemptId });
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, `${JSON.stringify(operation)}\n`);
+  return { status: "prepared", operation, ledgerPath: path };
+}
+
+export async function transitionExternalOperation({
+  runDir,
+  stageId,
+  attemptId,
+  operationId,
+  status,
+  patch = {}
+}) {
+  if (!allowedOperationStatuses.has(status)) {
+    throw new Error(`Unsupported operation status: ${status}`);
+  }
+  const reservedPatchKeys = ["schemaVersion", "operationId", "status", "recordedAt"];
+  const reservedKey = reservedPatchKeys.find((key) => Object.hasOwn(patch, key));
+  if (reservedKey) {
+    throw new Error(`Patch contains reserved ledger field: ${reservedKey}`);
+  }
+  const record = {
+    schemaVersion: "1.0.0",
+    ...patch,
+    operationId,
+    status,
+    recordedAt: new Date().toISOString()
+  };
+  const path = ledgerPath({ runDir, stageId, attemptId });
+  await mkdir(dirname(path), { recursive: true });
+  await appendFile(path, `${JSON.stringify(record)}\n`);
+  return record;
+}

package/lib/internal/pricing/default-preview-pricing.mjs

@@ -0,0 +1,181 @@
+export const DEFAULT_PREVIEW_PRICING_STRATEGY = Object.freeze({
+  id: "default-preview-pricing-v1",
+  currencyRates: Object.freeze({
+    CNY: Object.freeze({ USD: 0.14 }),
+    USD: Object.freeze({ USD: 1 })
+  }),
+  landedCostMultiplier: 2.8,
+  compareAtMultiplier: 1.25,
+  rounding: ".00"
+});
+
+function normalizeCurrency(value, fallback = "") {
+  return String(value || fallback).trim().toUpperCase();
+}
+
+function parsePositiveAmount(value) {
+  const amount = Number.parseFloat(String(value ?? ""));
+  return Number.isFinite(amount) && amount > 0 ? amount : undefined;
+}
+
+function roundAmount(value, rounding = ".00") {
+  if (rounding === ".00") {
+    return Math.round(value).toFixed(2);
+  }
+  return value.toFixed(2);
+}
+
+function formatSourceAmount(value) {
+  const amount = parsePositiveAmount(value);
+  return amount === undefined ? "" : amount.toFixed(2);
+}
+
+function strategyRate({ sourceCurrency, targetCurrency, strategy }) {
+  if (sourceCurrency === targetCurrency) {
+    return 1;
+  }
+  if (Number.isFinite(strategy.fxRate) && strategy.fxRate > 0) {
+    return strategy.fxRate;
+  }
+  const directRate = strategy.currencyRates?.[sourceCurrency]?.[targetCurrency];
+  return Number.isFinite(directRate) && directRate > 0 ? directRate : undefined;
+}
+
+function reviewResult({ sourceAmount, sourceCurrency, targetCurrency, status, strategy }) {
+  return {
+    amount: "",
+    currency: targetCurrency,
+    compareAtAmount: "",
+    compareAtCurrency: targetCurrency,
+    status,
+    merchantApprovalRequired: true,
+    warningTag: "price-review-required",
+    draftWriteBlocked: false,
+    provenance: {
+      sourceAmount: formatSourceAmount(sourceAmount),
+      sourceCurrency,
+      targetAmount: "",
+      targetCurrency,
+      strategyId: strategy.id,
+      fxRate: "",
+      landedCostMultiplier: strategy.landedCostMultiplier,
+      compareAtMultiplier: strategy.compareAtMultiplier,
+      rounding: strategy.rounding,
+      status,
+      merchantApprovalRequired: true
+    }
+  };
+}
+
+function userFormulaStrategy(userFormula) {
+  if (!userFormula) {
+    return DEFAULT_PREVIEW_PRICING_STRATEGY;
+  }
+  return {
+    id: userFormula.id || "user-provided-pricing-formula",
+    fxRate: userFormula.fxRate,
+    currencyRates: userFormula.currencyRates ?? DEFAULT_PREVIEW_PRICING_STRATEGY.currencyRates,
+    landedCostMultiplier: userFormula.landedCostMultiplier ?? DEFAULT_PREVIEW_PRICING_STRATEGY.landedCostMultiplier,
+    compareAtMultiplier: userFormula.compareAtMultiplier ?? DEFAULT_PREVIEW_PRICING_STRATEGY.compareAtMultiplier,
+    rounding: userFormula.rounding ?? DEFAULT_PREVIEW_PRICING_STRATEGY.rounding
+  };
+}
+
+export function derivePreviewPricing({
+  sourceAmount,
+  sourceCurrency,
+  targetCurrency = "USD",
+  userPrice,
+  userFormula
+} = {}) {
+  const normalizedTargetCurrency = normalizeCurrency(userPrice?.currency, normalizeCurrency(targetCurrency, "USD"));
+  const normalizedSourceCurrency = normalizeCurrency(sourceCurrency);
+  const approvedAmount = parsePositiveAmount(userPrice?.amount);
+  if (approvedAmount !== undefined) {
+    const amount = approvedAmount.toFixed(2);
+    return {
+      amount,
+      currency: normalizedTargetCurrency,
+      compareAtAmount: "",
+      compareAtCurrency: normalizedTargetCurrency,
+      status: "user-approved",
+      merchantApprovalRequired: false,
+      warningTag: "",
+      draftWriteBlocked: false,
+      provenance: {
+        sourceAmount: formatSourceAmount(sourceAmount),
+        sourceCurrency: normalizedSourceCurrency,
+        targetAmount: amount,
+        targetCurrency: normalizedTargetCurrency,
+        strategyId: "user-approved-price",
+        fxRate: "",
+        landedCostMultiplier: "",
+        compareAtMultiplier: "",
+        rounding: "",
+        status: "user-approved",
+        merchantApprovalRequired: false
+      }
+    };
+  }
+
+  const strategy = userFormulaStrategy(userFormula);
+  const amount = parsePositiveAmount(sourceAmount);
+  if (amount === undefined) {
+    return reviewResult({
+      sourceAmount,
+      sourceCurrency: normalizedSourceCurrency,
+      targetCurrency: normalizedTargetCurrency,
+      status: "missing",
+      strategy
+    });
+  }
+  if (!normalizedSourceCurrency) {
+    return reviewResult({
+      sourceAmount,
+      sourceCurrency: "",
+      targetCurrency: normalizedTargetCurrency,
+      status: "missing-source-currency",
+      strategy
+    });
+  }
+  const fxRate = strategyRate({
+    sourceCurrency: normalizedSourceCurrency,
+    targetCurrency: normalizedTargetCurrency,
+    strategy
+  });
+  if (!Number.isFinite(fxRate) || fxRate <= 0) {
+    return reviewResult({
+      sourceAmount,
+      sourceCurrency: normalizedSourceCurrency,
+      targetCurrency: normalizedTargetCurrency,
+      status: "missing-currency-rate",
+      strategy
+    });
+  }
+
+  const targetAmount = roundAmount(amount * fxRate * strategy.landedCostMultiplier, strategy.rounding);
+  const compareAtAmount = roundAmount(Number.parseFloat(targetAmount) * strategy.compareAtMultiplier, strategy.rounding);
+  return {
+    amount: targetAmount,
+    currency: normalizedTargetCurrency,
+    compareAtAmount,
+    compareAtCurrency: normalizedTargetCurrency,
+    status: "derived-preview",
+    merchantApprovalRequired: true,
+    warningTag: "price-review-required",
+    draftWriteBlocked: false,
+    provenance: {
+      sourceAmount: amount.toFixed(2),
+      sourceCurrency: normalizedSourceCurrency,
+      targetAmount,
+      targetCurrency: normalizedTargetCurrency,
+      strategyId: strategy.id,
+      fxRate,
+      landedCostMultiplier: strategy.landedCostMultiplier,
+      compareAtMultiplier: strategy.compareAtMultiplier,
+      rounding: strategy.rounding,
+      status: "derived-preview",
+      merchantApprovalRequired: true
+    }
+  };
+}

package/lib/internal/run-state-helpers.mjs

@@ -0,0 +1,313 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const runtimeRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const pluginRoot = resolve(runtimeRoot, "..");
+
+const stageOrder = [
+  "1 Intake",
+  "1A Shopify Access Preflight",
+  "2 Product Source Normalize",
+  "3 Supplier Extraction",
+  "4 Product Content",
+  "5 Merchandising Strategy",
+  "6 Brand Identity",
+  "7 Store Content",
+  "8 Design Direction",
+  "9 Store Blueprint",
+  "9A Media Production",
+  "9B Shopify Media Upload",
+  "10 Theme Build And Apply",
+  "11A Shopify Preflight Auth Scope",
+  "11B Shopify Products Collections",
+  "11C Shopify Content Navigation",
+  "11D Shopify Theme Push",
+  "11E Shopify Store Ops Consolidation",
+  "12 Launch Readiness"
+];
+
+const stageResumeContract = new Map([
+  ["1 Intake", { packet: "workflows/stages/01-intake.md", workerProfile: "intake-worker" }],
+  ["1A Shopify Access Preflight", { packet: "workflows/stages/01A-shopify-access-preflight.md", workerProfile: "shopify-access-preflight-worker" }],
+  ["2 Product Source Normalize", { packet: "workflows/stages/02-product-source-normalize.md", workerProfile: "product-source-normalize-worker" }],
+  ["3 Supplier Extraction", { packet: "workflows/stages/03-supplier-extraction.md", workerProfile: "supplier-extraction-worker" }],
+  ["4 Product Content", { packet: "workflows/stages/04-product-content.md", workerProfile: "product-content-worker" }],
+  ["5 Merchandising Strategy", { packet: "workflows/stages/05-merchandising-strategy.md", workerProfile: "merchandising-strategy-worker" }],
+  ["6 Brand Identity", { packet: "workflows/stages/06-brand-identity.md", workerProfile: "brand-identity-worker" }],
+  ["7 Store Content", { packet: "workflows/stages/07-store-content.md", workerProfile: "store-content-worker" }],
+  ["8 Design Direction", { packet: "workflows/stages/08-design-direction.md", workerProfile: "design-direction-worker" }],
+  ["9 Store Blueprint", { packet: "workflows/stages/09-store-blueprint.md", workerProfile: "store-blueprint-worker" }],
+  ["9A Media Production", { packet: "workflows/stages/09A-media-production.md", workerProfile: "media-production-worker" }],
+  ["9B Shopify Media Upload", { packet: "workflows/stages/09B-shopify-media-upload.md", workerProfile: "shopify-media-upload-worker" }],
+  ["10 Theme Build And Apply", { packet: "workflows/stages/10-theme-build-and-apply.md", workerProfile: "theme-build-worker" }],
+  ["11A Shopify Preflight Auth Scope", { packet: "workflows/stages/11A-shopify-preflight-auth-scope.md", workerProfile: "store-ops-preflight-worker" }],
+  ["11B Shopify Products Collections", { packet: "workflows/stages/11B-shopify-products-collections.md", workerProfile: "store-ops-products-worker" }],
+  ["11C Shopify Content Navigation", { packet: "workflows/stages/11C-shopify-content-navigation.md", workerProfile: "store-ops-content-worker" }],
+  ["11D Shopify Theme Push", { packet: "workflows/stages/11D-shopify-theme-push.md", workerProfile: "store-ops-theme-worker" }],
+  ["11E Shopify Store Ops Consolidation", { packet: "workflows/stages/11E-shopify-store-ops-consolidation.md", workerProfile: "store-ops-consolidation-worker" }],
+  ["12 Launch Readiness", { packet: "workflows/stages/12-launch-readiness.md", workerProfile: "launch-readiness-worker" }]
+]);
+
+async function readVersionText(path) {
+  return (await readFile(path, "utf8")).trim();
+}
+
+async function currentPluginVersionInfo() {
+  const manifestPath = join(pluginRoot, ".codex-plugin", "plugin.json");
+  if (!existsSync(manifestPath)) {
+    const pkg = JSON.parse(await readFile(join(runtimeRoot, "package.json"), "utf8"));
+    return {
+      name: pkg.name,
+      manifestVersion: "",
+      pluginVersion: await readVersionText(join(runtimeRoot, "VERSION")),
+      skillVersion: ""
+    };
+  }
+
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  return {
+    name: manifest.name,
+    manifestVersion: manifest.version,
+    pluginVersion: await readVersionText(join(pluginRoot, "VERSION")),
+    skillVersion: await readVersionText(join(pluginRoot, "storewright", "VERSION"))
+  };
+}
+
+function pluginVersionLines(info) {
+  return [
+    `Plugin: ${info.name}`,
+    `Manifest version: ${info.manifestVersion}`,
+    `Plugin version: ${info.pluginVersion}`,
+    `Skill version: ${info.skillVersion}`
+  ];
+}
+
+function stageRow({
+  stage,
+  workerProfile,
+  executionMode = "subagent",
+  status,
+  gate,
+  outputs,
+  notes
+}) {
+  return `| ${stage} | ${workerProfile} | ${executionMode} | ${status} | ${gate} | ${outputs} | ${notes} |`;
+}
+
+function nextStageAfter(completedStage, status) {
+  if (["blocked", "fatal", "repairable"].includes(status)) {
+    return completedStage;
+  }
+  const index = stageOrder.indexOf(completedStage);
+  return stageOrder[index + 1] ?? completedStage;
+}
+
+function stageResumeInstructions(stage) {
+  const contract = stageResumeContract.get(stage) ?? {
+    packet: "See the current stage packet.",
+    workerProfile: "stage-worker"
+  };
+
+  return [
+    "Next action:",
+    `Lead Agent must discover a real spawn/delegation tool and spawn ${contract.workerProfile} as the stage owner for ${stage}.`,
+    "Launch envelope:",
+    "Lead Agent must prepare the attempt control/launch-envelope.json before spawn, including resolved inputs, effectiveAllowedActions, and work/outputs path constraints.",
+    "Stage packet:",
+    contract.packet,
+    "Required input artifacts:",
+    "See the stage packet.",
+    "Worker trace:",
+    "Worker writes the trace artifact declared in the matching stage spec.",
+    "Expected worker handoff:",
+    `${contract.workerProfile} returns declared outputs under work/outputs, work/agent-report.json, and a concise handoff summary to the Lead Agent.`,
+    "After worker handoff:",
+    "Lead Agent applies the Lead-facing gate spec, writes the gate artifact, updates PROGRESS.md, and selects the next stage."
+  ].join("\n");
+}
+
+function workerRunningResumeInstructions(stage, activeWorker) {
+  const contract = stageResumeContract.get(stage) ?? {
+    workerProfile: activeWorker.profile ?? "stage-worker"
+  };
+  const workerProfile = activeWorker.profile ?? contract.workerProfile;
+
+  return [
+    "Next action:",
+    `Active worker: ${activeWorker.id}`,
+    `Wait for subagent_notification from ${workerProfile}.`,
+    "Do not interrupt or mark the run blocked because a wait_agent call reaches its timeout; that timeout is non-terminal while the worker is still running.",
+    "After worker handoff:",
+    "Lead Agent reads the worker handoff, work/agent-report.json, worker trace, and declared artifacts, then applies the Lead-facing gate spec."
+  ].join("\n");
+}
+
+function isCanonicalLaunchEnvelopePath(path) {
+  return /^stages\/[A-Za-z0-9_-]+\/attempts\/[A-Za-z0-9_-]+\/control\/launch-envelope\.json$/.test(path);
+}
+
+export async function writeWorkerRunningProgress({
+  runDir,
+  runId,
+  currentStage,
+  completedStages = [],
+  activeWorker,
+  pluginVersionInfo
+}) {
+  if (!activeWorker?.id) {
+    throw new Error("activeWorker.id is required");
+  }
+  if (!activeWorker.launchEnvelope) {
+    throw new Error("activeWorker.launchEnvelope is required");
+  }
+  if (!isCanonicalLaunchEnvelopePath(activeWorker.launchEnvelope)) {
+    throw new Error("activeWorker.launchEnvelope must be stages/<stage-id>/attempts/<attempt-id>/control/launch-envelope.json");
+  }
+  const contract = stageResumeContract.get(currentStage) ?? {
+    workerProfile: activeWorker.profile ?? "stage-worker"
+  };
+  const workerProfile = activeWorker.profile ?? contract.workerProfile;
+  const launchEnvelope = activeWorker.launchEnvelope;
+  const stageRows = [
+    ...completedStages.map(stageRow),
+    stageRow({
+      stage: currentStage,
+      workerProfile,
+      executionMode: "worker-running",
+      status: "in-progress",
+      gate: "-",
+      outputs: launchEnvelope,
+      notes: `Active worker ${activeWorker.id}; waiting for subagent notification.`
+    })
+  ].join("\n");
+  const versionInfo = pluginVersionInfo ?? await currentPluginVersionInfo();
+
+  const progress = [
+    "# Storewright Progress",
+    "",
+    `Run ID: ${runId}`,
+    ...pluginVersionLines(versionInfo),
+    "Workflow: workflows/official-build.md",
+    `Current stage: ${currentStage}`,
+    "Status: in-progress",
+    `Last updated: ${new Date().toISOString()}`,
+    "",
+    "## Stage Table",
+    "",
+    "| Stage | Worker profile | Execution mode | Status | Gate | Outputs | Notes |",
+    "| --- | --- | --- | --- | --- | --- | --- |",
+    stageRows,
+    "",
+    "## Current Blocker",
+    "",
+    "None",
+    "",
+    "## Resume Instructions",
+    "",
+    workerRunningResumeInstructions(currentStage, { ...activeWorker, profile: workerProfile }),
+    ""
+  ].join("\n");
+
+  const progressPath = join(runDir, "PROGRESS.md");
+  await writeFile(progressPath, progress);
+  return progressPath;
+}
+
+export async function writeProgress({
+  runDir,
+  runId,
+  completedStages,
+  latestStage,
+  latestStatus,
+  blocker = "None",
+  resumeInstructions,
+  pluginVersionInfo
+}) {
+  const currentStage = nextStageAfter(latestStage, latestStatus);
+  const progressStatus = latestStatus === "pass" || latestStatus === "warning" ? "in-progress" : latestStatus;
+  const stageRows = completedStages.map(stageRow).join("\n");
+  const versionInfo = pluginVersionInfo ?? await currentPluginVersionInfo();
+
+  const progress = [
+    "# Storewright Progress",
+    "",
+    `Run ID: ${runId}`,
+    ...pluginVersionLines(versionInfo),
+    "Workflow: workflows/official-build.md",
+    `Current stage: ${currentStage}`,
+    `Status: ${progressStatus}`,
+    `Last updated: ${new Date().toISOString()}`,
+    "",
+    "## Stage Table",
+    "",
+    "| Stage | Worker profile | Execution mode | Status | Gate | Outputs | Notes |",
+    "| --- | --- | --- | --- | --- | --- | --- |",
+    stageRows,
+    "",
+    "## Current Blocker",
+    "",
+    blocker,
+    "",
+    "## Resume Instructions",
+    "",
+    resumeInstructions ?? stageResumeInstructions(currentStage),
+    ""
+  ].join("\n");
+
+  const progressPath = join(runDir, "PROGRESS.md");
+  await writeFile(progressPath, progress);
+  return progressPath;
+}
+
+export function progressExists(runDir) {
+  return existsSync(join(runDir, "PROGRESS.md"));
+}
+
+export async function writeInitialProgress({ runDir, runId, pluginVersionInfo }) {
+  const versionInfo = pluginVersionInfo ?? await currentPluginVersionInfo();
+  const progress = [
+    "# Storewright Progress",
+    "",
+    `Run ID: ${runId}`,
+    ...pluginVersionLines(versionInfo),
+    "Workflow: workflows/official-build.md",
+    "Current stage: 1 Intake",
+    "Status: in-progress",
+    `Last updated: ${new Date().toISOString()}`,
+    "",
+    "## Stage Table",
+    "",
+    "| Stage | Worker profile | Execution mode | Status | Gate | Outputs | Notes |",
+    "| --- | --- | --- | --- | --- | --- | --- |",
+    "",
+    "## Current Blocker",
+    "",
+    "None",
+    "",
+    "## Resume Instructions",
+    "",
+    stageResumeInstructions("1 Intake"),
+    ""
+  ].join("\n");
+
+  const progressPath = join(runDir, "PROGRESS.md");
+  await writeFile(progressPath, progress);
+  return progressPath;
+}
+
+export function qualityGate({ runId, stage, status, checks, reasons = [], nextActions = [] }) {
+  return {
+    schemaVersion: "1.0.0",
+    runId,
+    qualityGate: {
+      stage,
+      status,
+      checks,
+      reasons,
+      nextActions,
+      retryCount: 0
+    }
+  };
+}