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

package/dist/index.js

@@ -9,15 +9,17 @@ import {
 } from "@prodshape/core";
 import { parse as parse2, stringify } from "yaml";
 
-// src/product-schema.ts
+// src/product-change-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";
+var OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME = "product-change";
+var OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE = "openspec/schemas/product-change";
+var PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC = "1.7.0";
+var OPENSPEC_PRODUCT_RECOVERY_SCHEMA_NAME = "product-recovery";
+var OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE = "openspec/schemas/product-recovery";
 function assetsDir() {
-  return fileURLToPath(new URL("../assets/openspec-product-schema/", import.meta.url));
+  return fileURLToPath(new URL("../assets/openspec-product-change-schema/", import.meta.url));
 }
 async function collectFiles(dir, prefix) {
   const entries = await readdir(dir, { withFileTypes: true });
@@ -32,7 +34,7 @@ async function collectFiles(dir, prefix) {
   }
   return files;
 }
-async function loadProductSchemaAssets() {
+async function loadProductChangeSchemaAssets() {
   const dir = assetsDir();
   const relatives = await collectFiles(dir, "");
   const assets = [];
@@ -44,6 +46,18 @@ async function loadProductSchemaAssets() {
   }
   return assets;
 }
+async function loadProductRecoverySchemaAssets() {
+  const dir = fileURLToPath(
+    new URL("../assets/openspec-product-recovery-schema/", import.meta.url)
+  );
+  const relatives = await collectFiles(dir, "");
+  return Promise.all(
+    relatives.sort((a, b) => a < b ? -1 : a > b ? 1 : 0).map(async (relative2) => ({
+      relative: relative2,
+      content: await readFile(join(dir, ...relative2.split("/")), "utf8")
+    }))
+  );
+}
 
 // src/process.ts
 import crossSpawn from "cross-spawn";
@@ -298,21 +312,20 @@ import { join as join4 } from "path";
 import { parse } from "yaml";
 import {
   analyzeImpact,
-  blockingDiagnostics,
   compareCodePoints,
-  dedupeDiagnostics,
   discoverChanges,
   executeApply,
   isNotFound,
   loadChange,
   openRepository,
-  planApply,
+  planHostedProductChange,
   preflightApply,
   sortDiagnostics,
   validateBaseline,
+  validateHostedProductChange,
   validateChange
 } from "@prodshape/core";
-var OPENSPEC_PRODUCT_SUBDIR = "product";
+var OPENSPEC_PRODUCT_SUBDIR = "product-change";
 var OPENSPEC_CHANGE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 function assertOpenSpecChangeName(changeName) {
   if (changeName.length > 200 || !OPENSPEC_CHANGE_NAME.test(changeName)) {
@@ -389,7 +402,7 @@ async function readHostedSchemaPin(changeDir) {
 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}.`
+      `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_CHANGE_SCHEMA_NAME}.`
     );
   }
   return new Error(
@@ -414,7 +427,7 @@ async function listOpenSpecProductChanges(root) {
     assertOpenSpecChangeName(name);
     const pin = await readHostedSchemaPin(changeDir);
     if ("problem" in pin) throw hostedSchemaPinError(name, pin);
-    if (pin.schema !== OPENSPEC_PRODUCT_SCHEMA_NAME) continue;
+    if (pin.schema !== OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME) continue;
     refs.push({
       name,
       dir,
@@ -437,16 +450,16 @@ async function loadHostedChange(root, repo, changeName) {
     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}).`
+      `No OpenSpec product change named '${changeName}' under openspec/changes/ (a product change hosts product-change/change.md; found: ${known}).`
     );
   }
   const pin = await readHostedSchemaPin(changeDir);
   if ("problem" in pin) {
     throw hostedSchemaPinError(changeName, pin);
   }
-  if (pin.schema !== OPENSPEC_PRODUCT_SCHEMA_NAME) {
+  if (pin.schema !== OPENSPEC_PRODUCT_CHANGE_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}.`
+      `OpenSpec change '${changeName}' is pinned to schema '${pin.schema}', not '${OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME}'; the hosted product rail refuses it. Product intent travels through a change created with: openspec new change <name> --schema ${OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME}.`
     );
   }
   return loadChange(deltaDir, repo.root, repo.registry);
@@ -470,27 +483,28 @@ async function validateOpenSpecProductChange(root, changeName) {
   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
-    ])
+  const hosted = validateHostedProductChange(
+    repo,
+    baseline.artifacts,
+    change,
+    all,
+    baseline.diagnostics
   );
+  const diagnostics = hosted.diagnostics;
   return {
     change,
     baseline,
     overlayArtifacts: validation.overlayArtifacts,
     overlayGraph: validation.overlayGraph,
     diagnostics,
-    blocking: blockingDiagnostics(diagnostics, repo.config.validation["warnings-as-errors"])
+    blocking: hosted.blocking
   };
 }
 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$/);
+  const match = relative2.match(/^openspec\/changes\/([^/]+)\/product-change$/);
   return match?.[1];
 }
 async function applyOpenSpecProductChange(root, changeName, options = {}) {
@@ -499,24 +513,20 @@ async function applyOpenSpecProductChange(root, changeName, options = {}) {
   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 hosted = validateHostedProductChange(
+    repo,
+    baseline.artifacts,
+    change,
+    all,
+    baseline.diagnostics
   );
-  const rawPlan = await planApply({
+  const rawPlan = await planHostedProductChange({
     repoRoot: repo.root,
     modelRelative: repo.config.product.model,
     changesRelative: repo.config.product.changes,
     change,
     baseline: baseline.artifacts,
-    overlayErrors
+    overlayErrors: hosted.blocking
   });
   const plan = {
     ...rawPlan,
@@ -596,14 +606,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: 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.
+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/change.md plus product-change/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, 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.",
+    "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-change 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: [
@@ -640,20 +650,22 @@ function currentManagedStrings() {
     )
   };
 }
+var LEGACY_OPENSPEC_PRODUCT_SCHEMA_NAME = "product";
+var LEGACY_OPENSPEC_PRODUCT_SCHEMA_RELATIVE = "openspec/schemas/product";
 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") {
+  if (typeof record !== "object" || record === null || record.name !== OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME && record.name !== LEGACY_OPENSPEC_PRODUCT_SCHEMA_NAME && record.name !== OPENSPEC_PRODUCT_RECOVERY_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);
+  const validatePath = (file) => typeof file === "string" && (file.startsWith(`${OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE}/`) || file.startsWith(`${LEGACY_OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/`) || file.startsWith(`${OPENSPEC_PRODUCT_RECOVERY_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}`
+        `'productSchema.files' contains a path outside the managed OpenSpec schema locations`
       );
     }
     return Object.fromEntries(files.map((file) => [file, ""]));
@@ -662,7 +674,7 @@ function recordedProductSchemaFiles(meta) {
     const entries = Object.entries(files);
     if (!entries.every(([file]) => validatePath(file))) {
       throw new Error(
-        `'productSchema.files' contains a path outside ${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}`
+        `'productSchema.files' contains a path outside the managed OpenSpec schema locations`
       );
     }
     if (!entries.every(
@@ -674,6 +686,19 @@ function recordedProductSchemaFiles(meta) {
   }
   throw new Error("'productSchema.files' must be a path-to-digest object or legacy path array");
 }
+function recordedRecoverySchemaFiles(meta) {
+  const record = meta?.recoverySchema;
+  if (!record) return void 0;
+  if (record.name !== OPENSPEC_PRODUCT_RECOVERY_SCHEMA_NAME || typeof record.requiresOpenspec !== "string") {
+    throw new Error(
+      "'recoverySchema' must name the product-recovery schema and carry a string 'requiresOpenspec'"
+    );
+  }
+  if (!record.files || typeof record.files !== "object" || Array.isArray(record.files)) {
+    throw new Error("'recoverySchema.files' must be a path-to-digest object");
+  }
+  return record.files;
+}
 var CONFIG_RELATIVE = "openspec/config.yaml";
 var META_RELATIVE = ".product/integrations/openspec.json";
 var CI_EXAMPLE_RELATIVE = ".product/integrations/openspec.ci.yml";
@@ -947,10 +972,10 @@ 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 schemaAssets = await loadProductChangeSchemaAssets();
   const recordedSchema = recordedProductSchemaFiles(previousMeta);
   const currentSchemaPaths = new Set(
-    schemaAssets.map((asset) => `${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/${asset.relative}`)
+    schemaAssets.map((asset) => `${OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE}/${asset.relative}`)
   );
   const schemaFileDigests = {};
   const schemaWrites = [];
@@ -959,7 +984,7 @@ async function addOpenSpecIntegration(root, options = {}) {
   const schemaPreserved = [];
   let schemaInstalledAnything = false;
   for (const asset of schemaAssets) {
-    const relative2 = `${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/${asset.relative}`;
+    const relative2 = `${OPENSPEC_PRODUCT_CHANGE_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);
@@ -1000,16 +1025,16 @@ async function addOpenSpecIntegration(root, options = {}) {
   }
   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.`
+      `Refusing to install the OpenSpec product schema: ${OPENSPEC_PRODUCT_CHANGE_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}.`
+      recordedSchema !== void 0 || !schemaInstalledAnything ? `Updated the OpenSpec product schema at ${OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE} (${schemaWrites.length} file${schemaWrites.length === 1 ? "" : "s"}).` : `Installed the OpenSpec product schema at ${OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE}.`
     );
-    if (compareVersions(openspecVersion, PRODUCT_SCHEMA_MIN_OPENSPEC) < 0) {
+    if (compareVersions(openspecVersion, PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC) < 0) {
       changes.push(
-        `Product workflow unavailable until OpenSpec >= ${PRODUCT_SCHEMA_MIN_OPENSPEC} (detected ${openspecVersion}); the citation lane is unaffected.`
+        `Product workflow unavailable until OpenSpec >= ${PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC} (detected ${openspecVersion}); the citation lane is unaffected.`
       );
     }
   }
@@ -1021,6 +1046,44 @@ async function addOpenSpecIntegration(root, options = {}) {
       `Preserved hand-edited managed file ${relative2}; restore or delete it, then run: prodshape integration update.`
     );
   }
+  const recoveryAssets = await loadProductRecoverySchemaAssets();
+  const previousRecovery = recordedRecoverySchemaFiles(previousMeta);
+  const recoveryDigests = {};
+  const recoveryWrites = [];
+  const recoveryCollisions = [];
+  for (const asset of recoveryAssets) {
+    const relative2 = `${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE}/${asset.relative}`;
+    const absolute = resolveInRepository(root, relative2, "the OpenSpec integration");
+    const existing2 = await pathExists(absolute) ? await readFile4(absolute, "utf8") : null;
+    const digest = contentDigest(asset.content);
+    const recorded = previousRecovery?.[relative2];
+    if (existing2 === null) {
+      recoveryWrites.push({ relative: relative2, absolute, content: asset.content });
+      recoveryDigests[relative2] = digest;
+    } else if (recorded === void 0) {
+      recoveryCollisions.push(relative2);
+    } else if (existing2 === asset.content) {
+      recoveryDigests[relative2] = digest;
+    } else if (recorded !== "" && contentDigest(existing2) === recorded) {
+      recoveryWrites.push({ relative: relative2, absolute, content: asset.content });
+      recoveryDigests[relative2] = digest;
+    } else {
+      recoveryDigests[relative2] = recorded;
+      changes.push(
+        `Preserved hand-edited managed file ${relative2}; restore or delete it, then run: prodshape integration update.`
+      );
+    }
+  }
+  if (recoveryCollisions.length > 0) {
+    throw new Error(
+      `Refusing to install the OpenSpec product-recovery schema: unrecorded files exist (${recoveryCollisions.join(", ")}). The integration never overwrites user-authored files.`
+    );
+  }
+  if (recoveryWrites.length > 0) {
+    changes.push(
+      previousRecovery === void 0 ? `Installed the OpenSpec product-recovery schema at ${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE}.` : `Updated the OpenSpec product-recovery schema at ${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE} (${recoveryWrites.length} files).`
+    );
+  }
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const meta = {
     provider: "openspec",
@@ -1031,9 +1094,14 @@ async function addOpenSpecIntegration(root, options = {}) {
     ciExamplePath: CI_EXAMPLE_RELATIVE,
     managed: currentManagedStrings(),
     productSchema: {
-      name: "product",
-      requiresOpenspec: PRODUCT_SCHEMA_MIN_OPENSPEC,
+      name: OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME,
+      requiresOpenspec: PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC,
       files: schemaFileDigests
+    },
+    recoverySchema: {
+      name: OPENSPEC_PRODUCT_RECOVERY_SCHEMA_NAME,
+      requiresOpenspec: PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC,
+      files: recoveryDigests
     }
   };
   const updatedAt = changes.length > 0 && previousMeta !== null ? now : previousMeta?.updatedAt ?? void 0;
@@ -1059,6 +1127,11 @@ async function addOpenSpecIntegration(root, options = {}) {
       await writeFile(write.absolute, write.content, "utf8");
       written.push(write.relative);
     }
+    for (const write of recoveryWrites) {
+      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);
     }
@@ -1132,10 +1205,12 @@ async function readMeta(root) {
   return meta;
 }
 async function updateOpenSpecIntegration(root, options = {}) {
+  const previousMeta = await readMeta(root);
   const result = await addOpenSpecIntegration(root, {
     force: true,
     dryRun: options.dryRun,
-    warningsAsErrors: options.warningsAsErrors
+    warningsAsErrors: options.warningsAsErrors,
+    ...previousMeta?.openspecVersion ? { cliVersion: previousMeta.openspecVersion } : {}
   });
   return { written: result.written, changes: result.changes };
 }
@@ -1234,17 +1309,17 @@ async function checkOpenSpecIntegration(root) {
       checks.push({ name: "rules", ok: true, detail: "All PDaC citation rules present." });
     }
   }
-  const schemaAssets = await loadProductSchemaAssets();
+  const schemaAssets = await loadProductChangeSchemaAssets();
   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`
+      detail: `OpenSpec product schema not installed (${OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE}). Run: prodshape integration update`
     });
   } else {
     const recordedSchema = recordedProductSchemaFiles(meta) ?? {};
     const currentSchemaPaths = new Set(
-      schemaAssets.map((asset) => `${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/${asset.relative}`)
+      schemaAssets.map((asset) => `${OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE}/${asset.relative}`)
     );
     const missing = [];
     const unrecorded = [];
@@ -1252,7 +1327,7 @@ async function checkOpenSpecIntegration(root) {
     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 relative2 = `${OPENSPEC_PRODUCT_CHANGE_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];
@@ -1304,20 +1379,52 @@ async function checkOpenSpecIntegration(root) {
         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) {
+    } else if (compareVersions(detectedVersion, PRODUCT_CHANGE_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.`
+        detail: `Product workflow UNAVAILABLE: requires OpenSpec >= ${PRODUCT_CHANGE_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.`
+        detail: `Product workflow available: schema installed and OpenSpec ${detectedVersion} meets the ${PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC} floor.`
       });
     }
   }
+  const recoveryAssets = await loadProductRecoverySchemaAssets();
+  const recoveryRecord = recordedRecoverySchemaFiles(meta);
+  if (recoveryRecord === void 0) {
+    checks.push({
+      name: "product recovery workflow",
+      // Existing installations predate #229. Keep the citation and existing product-change
+      // lanes healthy while advertising the opt-in migration; a fresh add/update records the
+      // recovery schema and is checked strictly below.
+      ok: true,
+      detail: `Product recovery workflow UNAVAILABLE: schema not installed (${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE}). Run: prodshape integration update to enable it.`
+    });
+  } else {
+    const defects = [];
+    for (const asset of recoveryAssets) {
+      const relative2 = `${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE}/${asset.relative}`;
+      const absolute = resolveInRepository(root, relative2, "the OpenSpec integration");
+      const expected = recoveryRecord[relative2];
+      if (expected === void 0) defects.push(`unrecorded: ${relative2}`);
+      else if (!await pathExists(absolute)) defects.push(`missing: ${relative2}`);
+      else {
+        const actual = await readFile4(absolute, "utf8");
+        if (actual !== asset.content && contentDigest(actual) !== expected) {
+          defects.push(`hand-edited and preserved: ${relative2}`);
+        } else if (actual !== asset.content) defects.push(`outdated managed content: ${relative2}`);
+      }
+    }
+    checks.push({
+      name: "product recovery workflow",
+      ok: defects.length === 0,
+      detail: defects.length === 0 ? `Product recovery workflow available: schema installed at ${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE}.` : `Product-recovery schema files need attention. ${defects.join(" ")}`
+    });
+  }
   const ok = checks.every((c) => c.ok);
   return { ok, checks };
 }
@@ -1430,8 +1537,8 @@ async function removeOpenSpecIntegration(root, options = {}) {
   const recordedSchema = recordedProductSchemaFiles(previousMeta);
   if (recordedSchema !== void 0) {
     const assetContentByRelative = new Map(
-      (await loadProductSchemaAssets()).map((asset) => [
-        `${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/${asset.relative}`,
+      (await loadProductChangeSchemaAssets()).map((asset) => [
+        `${OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE}/${asset.relative}`,
         asset.content
       ])
     );
@@ -1478,6 +1585,42 @@ async function removeOpenSpecIntegration(root, options = {}) {
       }
     }
   }
+  const recordedRecovery = recordedRecoverySchemaFiles(previousMeta);
+  if (recordedRecovery !== void 0) {
+    const recoveryAssets = new Map(
+      (await loadProductRecoverySchemaAssets()).map((asset) => [
+        `${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE}/${asset.relative}`,
+        asset.content
+      ])
+    );
+    for (const relative2 of Object.keys(recordedRecovery).sort()) {
+      const absolute = resolveInRepository(root, relative2, "the OpenSpec integration");
+      if (!await pathExists(absolute)) continue;
+      const existing = await readFile4(absolute, "utf8");
+      const recordedDigest = recordedRecovery[relative2];
+      const proven = existing === recoveryAssets.get(relative2) || recordedDigest !== "" && contentDigest(existing) === recordedDigest;
+      if (!proven) {
+        preserved.push(relative2);
+      } else {
+        if (!dryRun) await rm(absolute, { force: true });
+        removed.push(relative2);
+      }
+    }
+    if (!dryRun) {
+      for (const relative2 of [
+        `${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE}/templates`,
+        OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE,
+        "openspec/schemas"
+      ]) {
+        const absolute = resolveInRepository(root, relative2, "the OpenSpec integration");
+        try {
+          if ((await readdir4(absolute)).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 });
@@ -1491,15 +1634,17 @@ export {
   OPENSPEC_CI_EXAMPLE_RELATIVE,
   OPENSPEC_META_RELATIVE,
   OPENSPEC_NPX_SPEC,
-  OPENSPEC_PRODUCT_SCHEMA_NAME,
-  OPENSPEC_PRODUCT_SCHEMA_RELATIVE,
+  OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME,
+  OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE,
+  OPENSPEC_PRODUCT_RECOVERY_SCHEMA_NAME,
+  OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE,
   OPENSPEC_PRODUCT_SUBDIR,
   OPENSPEC_VERIFY_COMMAND,
   OpenSpecMetaError,
   PDAC_CONTEXT_BLOCK,
   PDAC_OPERATIONS,
   PDAC_RULES,
-  PRODUCT_SCHEMA_MIN_OPENSPEC,
+  PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC,
   addOpenSpecIntegration,
   applyOpenSpecProductChange,
   bootstrapOpenSpecWorkspace,
@@ -1514,7 +1659,8 @@ export {
   isOpenSpecWorkspace,
   listOpenSpecProductChanges,
   loadOpenSpecProductChange,
-  loadProductSchemaAssets,
+  loadProductChangeSchemaAssets,
+  loadProductRecoverySchemaAssets,
   mergeConfig,
   openSpecProvider,
   readOpenSpecConfig,