@prodshape/integration-openspec 0.5.2 → 0.6.0-alpha.0

package/dist/index.js

@@ -1,7 +1,49 @@
 // src/index.ts
-import { mkdir, readFile as readFile2, rm, writeFile } from "fs/promises";
-import { dirname, join as join3 } from "path";
-import { parse, stringify } from "yaml";
+import { mkdir, readdir as readdir4, readFile as readFile4, rm, rmdir, writeFile } from "fs/promises";
+import { dirname } from "path";
+import {
+  contentDigest,
+  isNotFound as isNotFound2,
+  isRepositoryRelativePath,
+  resolveInRepository
+} from "@prodshape/core";
+import { parse as parse2, stringify } from "yaml";
+
+// src/product-schema.ts
+import { readdir, readFile } from "fs/promises";
+import { fileURLToPath } from "url";
+import { join } from "path";
+var OPENSPEC_PRODUCT_SCHEMA_NAME = "product";
+var OPENSPEC_PRODUCT_SCHEMA_RELATIVE = "openspec/schemas/product";
+var PRODUCT_SCHEMA_MIN_OPENSPEC = "1.7.0";
+function assetsDir() {
+  return fileURLToPath(new URL("../assets/openspec-product-schema/", import.meta.url));
+}
+async function collectFiles(dir, prefix) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const relative2 = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      files.push(...await collectFiles(join(dir, entry.name), relative2));
+    } else if (entry.isFile()) {
+      files.push(relative2);
+    }
+  }
+  return files;
+}
+async function loadProductSchemaAssets() {
+  const dir = assetsDir();
+  const relatives = await collectFiles(dir, "");
+  const assets = [];
+  for (const relative2 of relatives.sort((a, b) => a < b ? -1 : a > b ? 1 : 0)) {
+    assets.push({
+      relative: relative2,
+      content: await readFile(join(dir, ...relative2.split("/")), "utf8")
+    });
+  }
+  return assets;
+}
 
 // src/process.ts
 import crossSpawn from "cross-spawn";
@@ -63,7 +105,7 @@ function runCommand(command, args, options = {}) {
 
 // src/workspace.ts
 import { access } from "fs/promises";
-import { join } from "path";
+import { join as join2 } from "path";
 async function pathExists(path) {
   try {
     await access(path);
@@ -73,7 +115,7 @@ async function pathExists(path) {
   }
 }
 async function isOpenSpecWorkspace(root) {
-  return pathExists(join(root, "openspec"));
+  return pathExists(join2(root, "openspec"));
 }
 function envWithLocalBin(root) {
   const env = { ...process.env };
@@ -85,15 +127,15 @@ function envWithLocalBin(root) {
       delete env[key];
     }
   }
-  const localBin = join(root, "node_modules", ".bin");
+  const localBin = join2(root, "node_modules", ".bin");
   env["PATH"] = existing ? `${localBin}${separator}${existing}` : localBin;
   return env;
 }
 
 // src/population.ts
 import { readFileSync } from "fs";
-import { readdir, readFile } from "fs/promises";
-import { join as join2, relative, sep } from "path";
+import { readdir as readdir2, readFile as readFile2 } from "fs/promises";
+import { join as join3, relative, sep } from "path";
 import fg from "fast-glob";
 import { codes } from "@prodshape/core";
 var CHANGE_ARTIFACT_FILES = [
@@ -149,16 +191,16 @@ function buildConsumerDocument(absolutePath, repoRoot, opts) {
 async function discoverChangeDocuments(changeDir, repoRoot, change, archived) {
   const docs = [];
   for (const { file, kind } of CHANGE_ARTIFACT_FILES) {
-    const absolutePath = join2(changeDir, file);
+    const absolutePath = join3(changeDir, file);
     try {
-      await readFile(absolutePath);
+      await readFile2(absolutePath);
       docs.push(
         buildConsumerDocument(absolutePath, repoRoot, { change, archived, artifactKind: kind })
       );
     } catch {
     }
   }
-  const specsDir = join2(changeDir, "specs");
+  const specsDir = join3(changeDir, "specs");
   try {
     const specFiles = await discoverMarkdownFiles(specsDir);
     for (const absolutePath of specFiles) {
@@ -185,7 +227,7 @@ async function discoverSpecDocuments(specsDir, repoRoot) {
 }
 async function discoverArchivedChanges(archiveDir) {
   try {
-    const entries = await readdir(archiveDir, { withFileTypes: true });
+    const entries = await readdir2(archiveDir, { withFileTypes: true });
     return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
   } catch {
     return [];
@@ -193,10 +235,10 @@ async function discoverArchivedChanges(archiveDir) {
 }
 async function enumerateOpenSpecDocuments(repoRoot, options) {
   const includeArchived = options?.includeArchived ?? false;
-  const root = join2(repoRoot, "openspec");
-  const changesDir = join2(root, "changes");
-  const archiveDir = join2(changesDir, "archive");
-  const specsDir = join2(root, "specs");
+  const root = join3(repoRoot, "openspec");
+  const changesDir = join3(root, "changes");
+  const archiveDir = join3(changesDir, "archive");
+  const specsDir = join3(root, "specs");
   const documents = [];
   const diagnostics = [];
   let currentChangeNames = await pathExists(changesDir) ? await openspecListChanges(repoRoot) : [];
@@ -208,7 +250,7 @@ async function enumerateOpenSpecDocuments(repoRoot, options) {
       file: "openspec/"
     });
     try {
-      const entries = await readdir(changesDir, { withFileTypes: true });
+      const entries = await readdir2(changesDir, { withFileTypes: true });
       currentChangeNames = entries.filter((e) => e.isDirectory() && e.name !== "archive").map((e) => e.name).sort();
     } catch {
       currentChangeNames = [];
@@ -223,14 +265,14 @@ async function enumerateOpenSpecDocuments(repoRoot, options) {
     }
   }
   for (const name of currentChangeNames) {
-    const changeDir = join2(changesDir, name);
+    const changeDir = join3(changesDir, name);
     documents.push(...await discoverChangeDocuments(changeDir, repoRoot, name, false));
   }
   if (includeArchived) {
     const archivedNames = await discoverArchivedChanges(archiveDir);
     for (const name of archivedNames) {
       if (options?.change && name !== options.change) continue;
-      const changeDir = join2(archiveDir, name);
+      const changeDir = join3(archiveDir, name);
       documents.push(...await discoverChangeDocuments(changeDir, repoRoot, name, true));
     }
   }
@@ -250,6 +292,299 @@ var openSpecProvider = {
   enumerateDocuments: enumerateOpenSpecDocuments
 };
 
+// src/product-workflow.ts
+import { readdir as readdir3, readFile as readFile3 } from "fs/promises";
+import { join as join4 } from "path";
+import { parse } from "yaml";
+import {
+  analyzeImpact,
+  blockingDiagnostics,
+  compareCodePoints,
+  dedupeDiagnostics,
+  discoverChanges,
+  executeApply,
+  isNotFound,
+  loadChange,
+  openRepository,
+  planApply,
+  preflightApply,
+  sortDiagnostics,
+  validateBaseline,
+  validateChange
+} from "@prodshape/core";
+var OPENSPEC_PRODUCT_SUBDIR = "product";
+var OPENSPEC_CHANGE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+function assertOpenSpecChangeName(changeName) {
+  if (changeName.length > 200 || !OPENSPEC_CHANGE_NAME.test(changeName)) {
+    throw new Error(
+      `OpenSpec change '${changeName}' is not a valid OpenSpec change name; use kebab-case with lowercase letters, numbers and single hyphen separators.`
+    );
+  }
+}
+async function inspectProductModel(root) {
+  const repo = await openRepository(root);
+  const baseline = await validateBaseline(repo);
+  return {
+    repo,
+    artifacts: baseline.artifacts,
+    graph: baseline.graph,
+    diagnostics: sortDiagnostics([...repo.configDiagnostics, ...baseline.diagnostics])
+  };
+}
+var OPEN_SPEC_KEBAB_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+function openSpecChangeMetadataProblem(parsed) {
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return "the document must be an object";
+  }
+  const record = parsed;
+  if (typeof record["schema"] !== "string" || record["schema"].length === 0) {
+    return "schema is required";
+  }
+  const created = record["created"];
+  if (created !== void 0 && (typeof created !== "string" || !/^\d{4}-\d{2}-\d{2}$/u.test(created))) {
+    return "created must be YYYY-MM-DD format";
+  }
+  const goal = record["goal"];
+  if (goal !== void 0 && (typeof goal !== "string" || goal.length === 0)) {
+    return "goal must be a non-empty string";
+  }
+  const affectedAreas = record["affected_areas"];
+  if (affectedAreas !== void 0 && (!Array.isArray(affectedAreas) || !affectedAreas.every((area) => typeof area === "string" && area.length > 0))) {
+    return "affected_areas must be an array of non-empty strings";
+  }
+  const initiative = record["initiative"];
+  if (initiative !== void 0) {
+    if (initiative === null || typeof initiative !== "object" || Array.isArray(initiative)) {
+      return "initiative must be an object";
+    }
+    const link = initiative;
+    if (Object.keys(link).some((key) => key !== "store" && key !== "id") || typeof link["store"] !== "string" || !OPEN_SPEC_KEBAB_ID.test(link["store"]) || typeof link["id"] !== "string" || !OPEN_SPEC_KEBAB_ID.test(link["id"])) {
+      return "initiative must contain only kebab-case store and id fields";
+    }
+  }
+  if (record["skip_specs"] !== void 0 && typeof record["skip_specs"] !== "boolean") {
+    return "skip_specs must be a boolean";
+  }
+  if (record["retire_capabilities"] !== void 0 && typeof record["retire_capabilities"] !== "boolean") {
+    return "retire_capabilities must be a boolean";
+  }
+  return void 0;
+}
+async function readHostedSchemaPin(changeDir) {
+  const metadataPath = join4(changeDir, ".openspec.yaml");
+  if (!await pathExists(metadataPath)) return { problem: "missing" };
+  let parsed;
+  try {
+    parsed = parse(await readFile3(metadataPath, "utf8"));
+  } catch (error) {
+    return {
+      problem: "malformed",
+      detail: error instanceof Error ? error.message : String(error)
+    };
+  }
+  const problem = openSpecChangeMetadataProblem(parsed);
+  if (problem !== void 0) return { problem: "malformed", detail: problem };
+  return { schema: parsed["schema"] };
+}
+function hostedSchemaPinError(changeName, pin) {
+  if (pin.problem === "missing") {
+    return new Error(
+      `OpenSpec change '${changeName}' has no .openspec.yaml, so its schema pin is unknown; the hosted product rail refuses it. Create product changes with: openspec new change ${changeName} --schema ${OPENSPEC_PRODUCT_SCHEMA_NAME}.`
+    );
+  }
+  return new Error(
+    `OpenSpec change '${changeName}' has an unreadable .openspec.yaml (${pin.detail}); the hosted product rail refuses it until the metadata is valid under OpenSpec 1.11.`
+  );
+}
+async function listOpenSpecProductChanges(root) {
+  const changesDir = join4(root, "openspec", "changes");
+  let entries;
+  try {
+    entries = await readdir3(changesDir, { withFileTypes: true });
+  } catch (error) {
+    if (isNotFound(error)) return [];
+    throw error;
+  }
+  const names = entries.filter((entry) => entry.isDirectory() && entry.name !== "archive").map((entry) => entry.name).sort(compareCodePoints);
+  const refs = [];
+  for (const name of names) {
+    const changeDir = join4(changesDir, name);
+    const dir = join4(changeDir, OPENSPEC_PRODUCT_SUBDIR);
+    if (!await pathExists(join4(dir, "change.md"))) continue;
+    assertOpenSpecChangeName(name);
+    const pin = await readHostedSchemaPin(changeDir);
+    if ("problem" in pin) throw hostedSchemaPinError(name, pin);
+    if (pin.schema !== OPENSPEC_PRODUCT_SCHEMA_NAME) continue;
+    refs.push({
+      name,
+      dir,
+      file: `openspec/changes/${name}/${OPENSPEC_PRODUCT_SUBDIR}/change.md`
+    });
+  }
+  return refs;
+}
+async function loadOpenSpecProductChange(root, changeName) {
+  const repo = await openRepository(root);
+  return loadHostedChange(root, repo, changeName);
+}
+async function loadHostedChange(root, repo, changeName) {
+  assertOpenSpecChangeName(changeName);
+  const changesDir = join4(root, "openspec", "changes");
+  const changeDir = join4(changesDir, changeName);
+  const deltaDir = join4(changeDir, OPENSPEC_PRODUCT_SUBDIR);
+  const hasDelta = changeName !== "archive" && await pathExists(changeDir) && await pathExists(join4(deltaDir, "change.md"));
+  if (!hasDelta) {
+    const refs = await listOpenSpecProductChanges(root);
+    const known = refs.map((candidate) => candidate.name).join(", ") || "none";
+    throw new Error(
+      `No OpenSpec product change named '${changeName}' under openspec/changes/ (a product change hosts product/change.md; found: ${known}).`
+    );
+  }
+  const pin = await readHostedSchemaPin(changeDir);
+  if ("problem" in pin) {
+    throw hostedSchemaPinError(changeName, pin);
+  }
+  if (pin.schema !== OPENSPEC_PRODUCT_SCHEMA_NAME) {
+    throw new Error(
+      `OpenSpec change '${changeName}' is pinned to schema '${pin.schema}', not '${OPENSPEC_PRODUCT_SCHEMA_NAME}'; the hosted product rail refuses it. Product intent travels through a change created with: openspec new change <name> --schema ${OPENSPEC_PRODUCT_SCHEMA_NAME}.`
+    );
+  }
+  return loadChange(deltaDir, repo.root, repo.registry);
+}
+var TERMINAL_CHANGE_STATUSES = /* @__PURE__ */ new Set(["applied", "rejected", "superseded"]);
+async function loadAllLiveChanges(root, repo) {
+  const changes = [];
+  for (const ref of await listOpenSpecProductChanges(root)) {
+    const loaded = await loadChange(ref.dir, repo.root, repo.registry);
+    if (loaded.status !== void 0 && TERMINAL_CHANGE_STATUSES.has(loaded.status)) continue;
+    changes.push(loaded);
+  }
+  for (const dir of await discoverChanges(join4(repo.changesDir, "active"))) {
+    changes.push(await loadChange(dir, repo.root, repo.registry));
+  }
+  return changes;
+}
+async function validateOpenSpecProductChange(root, changeName) {
+  const repo = await openRepository(root);
+  const baseline = await validateBaseline(repo);
+  const all = await loadAllLiveChanges(root, repo);
+  const change = all.find((candidate) => hostedName(root, candidate) === changeName) ?? await loadHostedChange(root, repo, changeName);
+  const validation = validateChange(change, baseline.artifacts, all);
+  const diagnostics = sortDiagnostics(
+    dedupeDiagnostics([
+      ...repo.configDiagnostics,
+      ...baseline.diagnostics,
+      ...validation.diagnostics
+    ])
+  );
+  return {
+    change,
+    baseline,
+    overlayArtifacts: validation.overlayArtifacts,
+    overlayGraph: validation.overlayGraph,
+    diagnostics,
+    blocking: blockingDiagnostics(diagnostics, repo.config.validation["warnings-as-errors"])
+  };
+}
+function hostedName(root, change) {
+  const normalizedRoot = root.replaceAll("\\", "/");
+  const normalizedDir = change.dir.replaceAll("\\", "/");
+  const relative2 = normalizedDir.startsWith(normalizedRoot) ? normalizedDir.slice(normalizedRoot.length).replace(/^\//, "") : normalizedDir;
+  const match = relative2.match(/^openspec\/changes\/([^/]+)\/product$/);
+  return match?.[1];
+}
+async function applyOpenSpecProductChange(root, changeName, options = {}) {
+  const { dryRun = false } = options;
+  const repo = await openRepository(root);
+  const baseline = await validateBaseline(repo);
+  const all = await loadAllLiveChanges(root, repo);
+  const change = all.find((candidate) => hostedName(root, candidate) === changeName) ?? await loadHostedChange(root, repo, changeName);
+  const validation = validateChange(change, baseline.artifacts, all);
+  const overlayErrors = blockingDiagnostics(
+    sortDiagnostics(
+      dedupeDiagnostics([
+        ...repo.configDiagnostics,
+        ...baseline.diagnostics,
+        ...validation.diagnostics
+      ])
+    ),
+    repo.config.validation["warnings-as-errors"]
+  );
+  const rawPlan = await planApply({
+    repoRoot: repo.root,
+    modelRelative: repo.config.product.model,
+    changesRelative: repo.config.product.changes,
+    change,
+    baseline: baseline.artifacts,
+    overlayErrors
+  });
+  const plan = {
+    ...rawPlan,
+    actions: rawPlan.actions.filter((action) => action.kind !== "move-change"),
+    // The hosted rail states authorisation as policy. Core's PRODUCT028 wording prescribes a
+    // human hand edit, which is the native lifecycle's own contract; here the code, severity,
+    // file and fields stay core's while the message (implementation-defined and never compared)
+    // says what the hosted contract requires. A message rewrite of an existing diagnostic, never
+    // a new emission.
+    diagnostics: rawPlan.diagnostics.map(
+      (diagnostic) => diagnostic.code === "PRODUCT028" ? {
+        ...diagnostic,
+        message: `Apply requires status 'approved'; the change is '${change.status ?? "unknown"}'. The transition into the apply-authorised state belongs to the caller's authorisation policy; the integration never performs or judges it.`
+      } : diagnostic
+    )
+  };
+  if (plan.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    return { outcome: "refused", plan, change };
+  }
+  if (dryRun) {
+    await preflightApply(repo.root, plan);
+    return { outcome: "dry-run", plan, change };
+  }
+  await executeApply(repo.root, plan);
+  const resultingModel = await validateBaseline(repo);
+  return { outcome: "applied", plan, change, resultingModel };
+}
+async function deriveDeliveryContext(root, ids) {
+  const inspection = await inspectProductModel(root);
+  const byId = new Map(
+    inspection.artifacts.filter((artifact) => artifact.id !== void 0).map((artifact) => [artifact.id, artifact])
+  );
+  const entryOf = (artifact) => {
+    const entry = {
+      id: artifact.id,
+      file: artifact.file,
+      digest: artifact.digest
+    };
+    if (artifact.type !== void 0) entry.type = artifact.type;
+    if (artifact.title !== void 0) entry.title = artifact.title;
+    if (artifact.status !== void 0) entry.status = artifact.status;
+    return entry;
+  };
+  const sortedIds = [...ids].sort(compareCodePoints);
+  const artifacts = [];
+  const impacts = {};
+  const neighbourIds = /* @__PURE__ */ new Set();
+  for (const id of sortedIds) {
+    const artifact = byId.get(id);
+    if (!artifact) {
+      throw new Error(`Unknown artifact id '${id}' in the accepted model at ${root}.`);
+    }
+    artifacts.push(entryOf(artifact));
+    const report = analyzeImpact(inspection.graph, id, { direction: "both", depth: 2 });
+    impacts[id] = report;
+    for (const item of report.direct) neighbourIds.add(item.id);
+  }
+  for (const id of sortedIds) neighbourIds.delete(id);
+  const neighbours = [...neighbourIds].sort(compareCodePoints).map((id) => byId.get(id)).filter((artifact) => artifact !== void 0).map(entryOf);
+  return {
+    ids: sortedIds,
+    artifacts,
+    impacts,
+    neighbours,
+    modelErrorFree: inspection.diagnostics.every((diagnostic) => diagnostic.severity !== "error")
+  };
+}
+
 // src/index.ts
 var MIN_SUPPORTED_OPENSPEC = "1.0.0";
 var OPENSPEC_NPX_SPEC = "@fission-ai/openspec@1";
@@ -261,14 +596,14 @@ A citation binds consumer text to a canonical artifact: it records the artifact
 To cite: run \`npx prodshape inspect <ID>\` to read the current digest, then \`npx prodshape cite --id <ID> --digest <digest>\` to emit the canonical payload. Wrap it in the document's native comment (\`<!-- ... -->\` in Markdown) on its own line directly under the text it grounds.
 To find which artifacts a change impacts, compare the change's intent with the whole product definition first, then widen the result with \`npx prodshape impact <ID>\`. When the intent contradicts or goes beyond the definition, record that drift in the proposal with the marker \`<!-- pdac-drift ids="..." summary="..." -->\` (listed by \`npx prodshape drift\`) and let humans decide \u2014 never fix it quietly.
 Every current OpenSpec document (proposal, specs, design, tasks and openspec/specs/) carries exactly one explicit scope declaration: \`pdac-scope: cited\` for a bound document that carries at least one citation, or \`pdac-scope: none\` with a non-empty human-authored reason (\`pdac-scope-reason: <why>\` in frontmatter, or \`<!-- pdac-scope: none reason="<why>" -->\`) for an exempt one. Citations alone never bind: a document without a declaration is unclassified and fails verification, a bound document with zero citations fails, and an exemption without a reason or contradicted by citations fails. Binding and exemption are human declarations: never declare an exemption merely because citations are missing. Verify with \`npx prodshape citations verify --provider openspec\`: it enumerates the expected current documents, so zero discovered citations is a set of failures, never a pass. Archived changes are excluded by default; \`--include-archived\` also verifies the citations history carries, reported as warnings, because archived history cannot be edited.
-The accepted Product Definition changes only through a Product Change under docs/product/changes/: validate it as an overlay while the baseline stays untouched, obtain human product approval, apply explicitly on a working branch, and let a human accept the resulting baseline by merging its pull request. A Product Change is not a pull request; apply is not acceptance; neither apply nor merge attests implementation, verification, release or deployment. OpenSpec changes never edit docs/product/model directly: an OpenSpec change may share a pull request with an applied Product Change or follow later, but it never supplies Product Change status.
+The accepted Product Definition changes only through a Product Change: validate it as an overlay while the baseline stays untouched, obtain human product approval (represented by status: approved; the integration verifies the state but cannot identify or judge the actor), apply explicitly on a working branch, and let a human accept the resulting baseline by merging its pull request. A Product Change is not a pull request; apply is not acceptance; neither apply nor merge attests implementation, verification, release or deployment. A Product Change lives under docs/product/changes/ or hosted inside a valid OpenSpec change created with the product schema (product/change.md plus product/proposed/**); its deterministically validated, apply-authorised apply is the only write path into docs/product/model. A spec-driven OpenSpec delivery change never edits docs/product/model directly: it may share a pull request with an applied Product Change or follow later, but it never supplies Product Change status.
 ${PDAC_CONTEXT_END}`;
 var PDAC_RULES = {
   proposal: [
     "State which PDaC artifacts this change touches, each with a citation payload emitted by `npx prodshape cite --id <ID> --digest <digest>` and wrapped in the document native comment (`<!-- ... -->` in Markdown). Never write a citation record by hand.",
     "Find the impacted artifacts as a separate step, before writing any proposal content. Read the whole product definition (docs/product/model by default), compare it with what this change wants \u2014 the backlog item behind it, if there is one \u2014 and list every artifact the change depends on, alters or contradicts. Then widen the list: run `npx prodshape impact <ID>` on each artifact you found and check its direct and indirect neighbours. Put the resulting list in the proposal, cite every impacted artifact from each document that uses it (proposal, specs, design, tasks), and name any neighbour you checked and left out.",
     'If this change\'s goals contradict the product definition, or need behaviour it does not describe, that is product-definition drift. Record it in the proposal under a \'Product definition drift\' note naming the artifacts involved, with the marker `<!-- pdac-drift ids="<ID>[, <ID>...]" summary="<one line>" -->` on its own line so `npx prodshape drift` can list it. The decision is human: the developer and the product owner agree whether to propose a Product Change or adjust this change. Never fix drift quietly, drop or weaken a citation to hide it, or write around the conflict.',
-    "If the change implements altered product behaviour, name the Product Change (CHG id) whose applied or accepted artifacts it implements. If no overlay-validated and human-approved Product Change exists yet, stop and ask for one instead of proceeding. The OpenSpec change is not the Product Change.",
+    "If the change implements altered product behaviour, name the Product Change (CHG id) whose applied or accepted artifacts it implements. If no overlay-validated, apply-authorised Product Change exists yet, stop and ask for one instead of proceeding. A spec-driven OpenSpec change is not the Product Change; product intent travels through a Product Change, under docs/product/changes or hosted by a product-schema OpenSpec change.",
     'Every document of this change must end up bound or exempt, each with an explicit declaration: declare `pdac-scope: cited` on a line of its own and cite the canonical text the document depends on, or declare `pdac-scope: none` with a non-empty reason (`pdac-scope-reason: <why>` in frontmatter, or `<!-- pdac-scope: none reason="<why>" -->`) when a human judges the document has no product-semantic dependency. Citations alone never bind, and never declare an exemption just because citations are missing.'
   ],
   specs: [
@@ -305,6 +640,40 @@ function currentManagedStrings() {
     )
   };
 }
+function recordedProductSchemaFiles(meta) {
+  const record = meta?.productSchema;
+  if (!record) return void 0;
+  if (typeof record !== "object" || record === null || record.name !== OPENSPEC_PRODUCT_SCHEMA_NAME || typeof record.requiresOpenspec !== "string") {
+    throw new Error(
+      "'productSchema' must name the product schema and carry a string 'requiresOpenspec'"
+    );
+  }
+  const files = record.files;
+  const validatePath = (file) => typeof file === "string" && file.startsWith(`${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/`) && isRepositoryRelativePath(file);
+  if (Array.isArray(files)) {
+    if (!files.every(validatePath)) {
+      throw new Error(
+        `'productSchema.files' contains a path outside ${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}`
+      );
+    }
+    return Object.fromEntries(files.map((file) => [file, ""]));
+  }
+  if (files !== null && typeof files === "object") {
+    const entries = Object.entries(files);
+    if (!entries.every(([file]) => validatePath(file))) {
+      throw new Error(
+        `'productSchema.files' contains a path outside ${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}`
+      );
+    }
+    if (!entries.every(
+      ([, digest]) => typeof digest === "string" && /^sha256:[0-9a-f]{64}$/.test(digest)
+    )) {
+      throw new Error("'productSchema.files' contains an invalid content digest");
+    }
+    return Object.fromEntries(entries);
+  }
+  throw new Error("'productSchema.files' must be a path-to-digest object or legacy path array");
+}
 var CONFIG_RELATIVE = "openspec/config.yaml";
 var META_RELATIVE = ".product/integrations/openspec.json";
 var CI_EXAMPLE_RELATIVE = ".product/integrations/openspec.ci.yml";
@@ -358,13 +727,13 @@ function renderCiExample(options) {
   ].join("\n");
 }
 function configPath(root) {
-  return join3(root, ...CONFIG_RELATIVE.split("/"));
+  return resolveInRepository(root, CONFIG_RELATIVE, "the OpenSpec integration");
 }
 function metaPath(root) {
-  return join3(root, ...META_RELATIVE.split("/"));
+  return resolveInRepository(root, META_RELATIVE, "the OpenSpec integration");
 }
 function ciExamplePath(root) {
-  return join3(root, ...CI_EXAMPLE_RELATIVE.split("/"));
+  return resolveInRepository(root, CI_EXAMPLE_RELATIVE, "the OpenSpec integration");
 }
 function compareVersions(a, b) {
   const parseParts = (v) => {
@@ -433,8 +802,8 @@ async function isOpenSpecIntegrationInstalled(root) {
 async function readOpenSpecConfig(root) {
   const path = configPath(root);
   if (!await pathExists(path)) return null;
-  const text = await readFile2(path, "utf8");
-  const parsed = parse(text);
+  const text = await readFile4(path, "utf8");
+  const parsed = parse2(text);
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
     return {};
   }
@@ -543,12 +912,12 @@ function serializeConfig(config) {
 }
 async function productshapeVersion() {
   const packageJson = JSON.parse(
-    await readFile2(new URL("../package.json", import.meta.url), "utf8")
+    await readFile4(new URL("../package.json", import.meta.url), "utf8")
   );
   return packageJson.version;
 }
 async function addOpenSpecIntegration(root, options = {}) {
-  const { force = false, dryRun = false, warningsAsErrors = false } = options;
+  const { dryRun = false, warningsAsErrors = false } = options;
   let openspecVersion = options.cliVersion;
   if (!openspecVersion) {
     const detected = await detectOpenSpecVersion(root);
@@ -570,7 +939,7 @@ async function addOpenSpecIntegration(root, options = {}) {
   const { config, changes: configChanges } = mergeConfig(existing, previousMeta?.managed);
   const ciDesired = renderCiExample({ warningsAsErrors });
   const ciAbsolute = ciExamplePath(root);
-  const ciExisting = await pathExists(ciAbsolute) ? await readFile2(ciAbsolute, "utf8") : null;
+  const ciExisting = await pathExists(ciAbsolute) ? await readFile4(ciAbsolute, "utf8") : null;
   const ciChanged = ciExisting !== ciDesired;
   const changes = [...configChanges];
   if (ciChanged) {
@@ -578,49 +947,189 @@ async function addOpenSpecIntegration(root, options = {}) {
       ciExisting === null ? `Installed CI-ready verification example at ${CI_EXAMPLE_RELATIVE}.` : `Updated CI-ready verification example at ${CI_EXAMPLE_RELATIVE}.`
     );
   }
+  const schemaAssets = await loadProductSchemaAssets();
+  const recordedSchema = recordedProductSchemaFiles(previousMeta);
+  const currentSchemaPaths = new Set(
+    schemaAssets.map((asset) => `${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/${asset.relative}`)
+  );
+  const schemaFileDigests = {};
+  const schemaWrites = [];
+  const schemaDeletes = [];
+  const schemaCollisions = [];
+  const schemaPreserved = [];
+  let schemaInstalledAnything = false;
+  for (const asset of schemaAssets) {
+    const relative2 = `${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/${asset.relative}`;
+    const absolute = resolveInRepository(root, relative2, "the OpenSpec integration");
+    const existing2 = await pathExists(absolute) ? await readFile4(absolute, "utf8") : null;
+    const assetDigest = contentDigest(asset.content);
+    if (existing2 === null) {
+      schemaWrites.push({ relative: relative2, absolute, content: asset.content });
+      schemaFileDigests[relative2] = assetDigest;
+      schemaInstalledAnything = true;
+      continue;
+    }
+    const recordedDigest = recordedSchema?.[relative2];
+    if (recordedDigest === void 0) {
+      schemaCollisions.push(relative2);
+      continue;
+    }
+    if (existing2 === asset.content) {
+      schemaFileDigests[relative2] = assetDigest;
+      continue;
+    }
+    if (recordedDigest !== "" && contentDigest(existing2) === recordedDigest) {
+      schemaWrites.push({ relative: relative2, absolute, content: asset.content });
+      schemaFileDigests[relative2] = assetDigest;
+      continue;
+    }
+    schemaPreserved.push(relative2);
+    if (recordedDigest !== "") schemaFileDigests[relative2] = recordedDigest;
+  }
+  for (const [relative2, recordedDigest] of Object.entries(recordedSchema ?? {})) {
+    if (currentSchemaPaths.has(relative2)) continue;
+    const absolute = resolveInRepository(root, relative2, "the OpenSpec integration");
+    if (!await pathExists(absolute)) continue;
+    const existing2 = await readFile4(absolute, "utf8");
+    if (recordedDigest !== "" && contentDigest(existing2) === recordedDigest) {
+      schemaDeletes.push({ relative: relative2, absolute });
+      continue;
+    }
+    schemaPreserved.push(relative2);
+    if (recordedDigest !== "") schemaFileDigests[relative2] = recordedDigest;
+  }
+  if (schemaCollisions.length > 0) {
+    throw new Error(
+      `Refusing to install the OpenSpec product schema: ${OPENSPEC_PRODUCT_SCHEMA_RELATIVE} already contains files this integration does not manage (${schemaCollisions.join(", ")}). Move them aside or delete them, then run: prodshape integration add openspec. The integration never overwrites user-authored files.`
+    );
+  }
+  if (schemaWrites.length > 0) {
+    changes.push(
+      recordedSchema !== void 0 || !schemaInstalledAnything ? `Updated the OpenSpec product schema at ${OPENSPEC_PRODUCT_SCHEMA_RELATIVE} (${schemaWrites.length} file${schemaWrites.length === 1 ? "" : "s"}).` : `Installed the OpenSpec product schema at ${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}.`
+    );
+    if (compareVersions(openspecVersion, PRODUCT_SCHEMA_MIN_OPENSPEC) < 0) {
+      changes.push(
+        `Product workflow unavailable until OpenSpec >= ${PRODUCT_SCHEMA_MIN_OPENSPEC} (detected ${openspecVersion}); the citation lane is unaffected.`
+      );
+    }
+  }
+  for (const { relative: relative2 } of schemaDeletes) {
+    changes.push(`Removed obsolete managed file ${relative2}.`);
+  }
+  for (const relative2 of schemaPreserved) {
+    changes.push(
+      `Preserved hand-edited managed file ${relative2}; restore or delete it, then run: prodshape integration update.`
+    );
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
   const meta = {
     provider: "openspec",
     version: await productshapeVersion(),
     openspecVersion,
-    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    installedAt: previousMeta?.installedAt ?? now,
     configPath: CONFIG_RELATIVE,
     ciExamplePath: CI_EXAMPLE_RELATIVE,
-    managed: currentManagedStrings()
-  };
-  if (changes.length === 0 && !force) {
-    if (!dryRun) {
-      await writeMeta(root, meta);
+    managed: currentManagedStrings(),
+    productSchema: {
+      name: "product",
+      requiresOpenspec: PRODUCT_SCHEMA_MIN_OPENSPEC,
+      files: schemaFileDigests
     }
-    return { written: [], changes: [], meta };
-  }
+  };
+  const updatedAt = changes.length > 0 && previousMeta !== null ? now : previousMeta?.updatedAt ?? void 0;
+  if (updatedAt !== void 0) meta.updatedAt = updatedAt;
   const written = [];
   if (!dryRun) {
-    if (configChanges.length > 0 || force) {
+    if (configChanges.length > 0) {
       const serialized = serializeConfig(config);
       await mkdir(dirname(configPath(root)), { recursive: true });
       await writeFile(configPath(root), serialized, "utf8");
       written.push(CONFIG_RELATIVE);
     }
-    if (ciChanged || force) {
+    if (ciChanged) {
       await mkdir(dirname(ciAbsolute), { recursive: true });
       await writeFile(ciAbsolute, ciDesired, "utf8");
       written.push(CI_EXAMPLE_RELATIVE);
     }
-    await writeMeta(root, meta);
-    written.push(META_RELATIVE);
+    for (const deletion of schemaDeletes) {
+      await rm(deletion.absolute, { force: true });
+    }
+    for (const write of schemaWrites) {
+      await mkdir(dirname(write.absolute), { recursive: true });
+      await writeFile(write.absolute, write.content, "utf8");
+      written.push(write.relative);
+    }
+    if (await writeMetaIfChanged(root, meta)) {
+      written.push(META_RELATIVE);
+    }
   }
   return { written, changes, meta };
 }
-async function writeMeta(root, meta) {
+async function writeMetaIfChanged(root, meta) {
   const path = metaPath(root);
+  const desired = `${JSON.stringify(meta, null, 2)}
+`;
+  let existing;
+  try {
+    existing = await readFile4(path, "utf8");
+  } catch (error) {
+    if (!isNotFound2(error)) throw error;
+  }
+  if (existing === desired) return false;
   await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, `${JSON.stringify(meta, null, 2)}
-`, "utf8");
+  await writeFile(path, desired, "utf8");
+  return true;
 }
+var OpenSpecMetaError = class extends Error {
+  constructor(detail, options) {
+    super(
+      `OpenSpec integration metadata ${META_RELATIVE} cannot be trusted: ${detail}
+Reconcile it by hand, or remove it and re-run: prodshape integration add openspec`,
+      options
+    );
+    this.name = "OpenSpecMetaError";
+  }
+};
 async function readMeta(root) {
   const path = metaPath(root);
-  if (!await pathExists(path)) return null;
-  return JSON.parse(await readFile2(path, "utf8"));
+  let content;
+  try {
+    content = await readFile4(path, "utf8");
+  } catch (error) {
+    if (isNotFound2(error)) return null;
+    throw new OpenSpecMetaError(
+      `it exists but could not be read (${error instanceof Error ? error.message : String(error)})`,
+      { cause: error }
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    throw new OpenSpecMetaError(
+      `it is not valid JSON (${error instanceof Error ? error.message : String(error)})`,
+      { cause: error }
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new OpenSpecMetaError("the document is not a JSON object");
+  }
+  const record = parsed;
+  if (record.provider !== "openspec" || typeof record.installedAt !== "string") {
+    throw new OpenSpecMetaError(
+      "it does not match the metadata schema ('provider' must be 'openspec' and 'installedAt' a string)"
+    );
+  }
+  const meta = record;
+  try {
+    recordedProductSchemaFiles(meta);
+  } catch (error) {
+    throw new OpenSpecMetaError(
+      `it does not match the product schema ownership record (${error instanceof Error ? error.message : String(error)})`,
+      { cause: error }
+    );
+  }
+  return meta;
 }
 async function updateOpenSpecIntegration(root, options = {}) {
   const result = await addOpenSpecIntegration(root, {
@@ -633,6 +1142,7 @@ async function updateOpenSpecIntegration(root, options = {}) {
 async function checkOpenSpecIntegration(root) {
   const checks = [];
   const detected = await detectOpenSpecVersion(root);
+  const detectedVersion = "error" in detected ? void 0 : detected.version;
   if ("error" in detected) {
     checks.push({ name: "openspec CLI", ok: false, detail: detected.error });
   } else if (compareVersions(detected.version, MIN_SUPPORTED_OPENSPEC) < 0) {
@@ -689,7 +1199,7 @@ async function checkOpenSpecIntegration(root) {
     checks.push({
       name: "metadata",
       ok: true,
-      detail: `Integration recorded (OpenSpec ${meta.openspecVersion}, installed ${meta.installedAt}).`
+      detail: `Integration recorded (OpenSpec ${meta.openspecVersion}, installed ${meta.installedAt}${meta.updatedAt ? `, updated ${meta.updatedAt}` : ""}).`
     });
   }
   if (await pathExists(ciExamplePath(root))) {
@@ -724,13 +1234,99 @@ async function checkOpenSpecIntegration(root) {
       checks.push({ name: "rules", ok: true, detail: "All PDaC citation rules present." });
     }
   }
+  const schemaAssets = await loadProductSchemaAssets();
+  if (meta === null || meta.productSchema === void 0) {
+    checks.push({
+      name: "product workflow",
+      ok: false,
+      detail: `OpenSpec product schema not installed (${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}). Run: prodshape integration update`
+    });
+  } else {
+    const recordedSchema = recordedProductSchemaFiles(meta) ?? {};
+    const currentSchemaPaths = new Set(
+      schemaAssets.map((asset) => `${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/${asset.relative}`)
+    );
+    const missing = [];
+    const unrecorded = [];
+    const outdated = [];
+    const diverged = [];
+    const obsolete = Object.keys(recordedSchema).filter((relative2) => !currentSchemaPaths.has(relative2)).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+    for (const asset of schemaAssets) {
+      const relative2 = `${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/${asset.relative}`;
+      const absolute = resolveInRepository(root, relative2, "the OpenSpec integration");
+      const existing = await pathExists(absolute) ? await readFile4(absolute, "utf8") : null;
+      const recordedDigest = recordedSchema[relative2];
+      if (recordedDigest === void 0) {
+        unrecorded.push(relative2);
+      } else if (existing === null) {
+        missing.push(relative2);
+      } else if (existing !== asset.content) {
+        if (recordedDigest !== "" && contentDigest(existing) === recordedDigest) {
+          outdated.push(relative2);
+        } else {
+          diverged.push(relative2);
+        }
+      }
+    }
+    if (missing.length > 0 || unrecorded.length > 0 || outdated.length > 0 || diverged.length > 0 || obsolete.length > 0) {
+      const parts = [];
+      if (missing.length > 0) {
+        parts.push(`missing: ${missing.join(", ")} (run: prodshape integration update)`);
+      }
+      if (unrecorded.length > 0) {
+        parts.push(
+          `unrecorded: ${unrecorded.join(", ")} (move user files aside, then run: prodshape integration update)`
+        );
+      }
+      if (outdated.length > 0) {
+        parts.push(
+          `outdated managed content: ${outdated.join(", ")} (run: prodshape integration update)`
+        );
+      }
+      if (diverged.length > 0) {
+        parts.push(
+          `hand-edited and preserved: ${diverged.join(", ")} (restore or delete them, then run: prodshape integration update)`
+        );
+      }
+      if (obsolete.length > 0) {
+        parts.push(
+          `obsolete managed content: ${obsolete.join(", ")} (run: prodshape integration update)`
+        );
+      }
+      checks.push({
+        name: "product workflow",
+        ok: false,
+        detail: `Product schema files need attention. ${parts.join(" ")}`
+      });
+    } else if (detectedVersion === void 0) {
+      checks.push({
+        name: "product workflow",
+        ok: true,
+        detail: "Product workflow UNAVAILABLE: the OpenSpec CLI was not detected. The schema is installed and intact; the openspec CLI check carries the remedy."
+      });
+    } else if (compareVersions(detectedVersion, PRODUCT_SCHEMA_MIN_OPENSPEC) < 0) {
+      checks.push({
+        name: "product workflow",
+        ok: true,
+        detail: `Product workflow UNAVAILABLE: requires OpenSpec >= ${PRODUCT_SCHEMA_MIN_OPENSPEC}, detected ${detectedVersion}. The citation lane is unaffected; upgrade OpenSpec to use the product schema.`
+      });
+    } else {
+      checks.push({
+        name: "product workflow",
+        ok: true,
+        detail: `Product workflow available: schema installed and OpenSpec ${detectedVersion} meets the ${PRODUCT_SCHEMA_MIN_OPENSPEC} floor.`
+      });
+    }
+  }
   const ok = checks.every((c) => c.ok);
   return { ok, checks };
 }
 async function removeOpenSpecIntegration(root, options = {}) {
   const { dryRun = false } = options;
   const removed = [];
-  const recorded = (await readMeta(root))?.managed;
+  const preserved = [];
+  const previousMeta = await readMeta(root);
+  const recorded = previousMeta?.managed;
   const current = currentManagedStrings();
   const managedRules = {};
   for (const key of /* @__PURE__ */ new Set([
@@ -831,38 +1427,101 @@ async function removeOpenSpecIntegration(root, options = {}) {
     }
     removed.push(CI_EXAMPLE_RELATIVE);
   }
+  const recordedSchema = recordedProductSchemaFiles(previousMeta);
+  if (recordedSchema !== void 0) {
+    const assetContentByRelative = new Map(
+      (await loadProductSchemaAssets()).map((asset) => [
+        `${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/${asset.relative}`,
+        asset.content
+      ])
+    );
+    const schemaFileSet = Object.keys(recordedSchema).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+    const pruneCandidates = /* @__PURE__ */ new Set();
+    for (const relative2 of schemaFileSet) {
+      const absolute = resolveInRepository(root, relative2, "the OpenSpec integration");
+      if (!await pathExists(absolute)) continue;
+      const existing = await readFile4(absolute, "utf8");
+      const recordedDigest = recordedSchema[relative2];
+      const proven = existing === assetContentByRelative.get(relative2) || recordedDigest !== void 0 && recordedDigest !== "" && contentDigest(existing) === recordedDigest;
+      if (!proven) {
+        preserved.push(relative2);
+        continue;
+      }
+      if (!dryRun) {
+        await rm(absolute, { force: true });
+        let parent = dirname(relative2);
+        while (parent.startsWith("openspec/schemas") && parent !== "openspec/schemas" && parent !== "openspec") {
+          pruneCandidates.add(parent);
+          parent = parent.split("/").slice(0, -1).join("/");
+        }
+        pruneCandidates.add("openspec/schemas");
+      }
+      removed.push(relative2);
+    }
+    for (const relative2 of [...assetContentByRelative.keys()].sort(
+      (a, b) => a < b ? -1 : a > b ? 1 : 0
+    )) {
+      if (recordedSchema[relative2] !== void 0) continue;
+      const absolute = resolveInRepository(root, relative2, "the OpenSpec integration");
+      if (await pathExists(absolute)) preserved.push(relative2);
+    }
+    if (!dryRun) {
+      const ordered = [...pruneCandidates].sort((a, b) => b.length - a.length);
+      for (const relative2 of ordered) {
+        const absolute = resolveInRepository(root, relative2, "the OpenSpec integration");
+        try {
+          const entries = await readdir4(absolute);
+          if (entries.length === 0) await rmdir(absolute);
+        } catch (error) {
+          if (!isNotFound2(error)) throw error;
+        }
+      }
+    }
+  }
   if (await pathExists(metaPath(root))) {
     if (!dryRun) {
       await rm(metaPath(root), { force: true });
     }
     removed.push(META_RELATIVE);
   }
-  return { removed };
+  return { removed, preserved };
 }
 export {
   MIN_SUPPORTED_OPENSPEC,
   OPENSPEC_CI_EXAMPLE_RELATIVE,
   OPENSPEC_META_RELATIVE,
   OPENSPEC_NPX_SPEC,
+  OPENSPEC_PRODUCT_SCHEMA_NAME,
+  OPENSPEC_PRODUCT_SCHEMA_RELATIVE,
+  OPENSPEC_PRODUCT_SUBDIR,
   OPENSPEC_VERIFY_COMMAND,
+  OpenSpecMetaError,
   PDAC_CONTEXT_BLOCK,
   PDAC_OPERATIONS,
   PDAC_RULES,
+  PRODUCT_SCHEMA_MIN_OPENSPEC,
   addOpenSpecIntegration,
+  applyOpenSpecProductChange,
   bootstrapOpenSpecWorkspace,
   checkOpenSpecIntegration,
   currentManagedStrings,
+  deriveDeliveryContext,
   detectOpenSpecVersion,
   enumerateOpenSpecDocuments,
+  inspectProductModel,
   isOpenSpecCliAvailable,
   isOpenSpecIntegrationInstalled,
   isOpenSpecWorkspace,
+  listOpenSpecProductChanges,
+  loadOpenSpecProductChange,
+  loadProductSchemaAssets,
   mergeConfig,
   openSpecProvider,
   readOpenSpecConfig,
   removeOpenSpecIntegration,
   renderCiExample,
   serializeConfig,
-  updateOpenSpecIntegration
+  updateOpenSpecIntegration,
+  validateOpenSpecProductChange
 };
 //# sourceMappingURL=index.js.map