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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prodshape/integration-openspec",
-  "version": "0.6.0-alpha.0",
+  "version": "0.6.0-alpha.3",
   "description": "OpenSpec integration for Product Definition as Code: configures OpenSpec workspaces with PDaC citation rules and verifies citations against the OpenSpec population.",
   "license": "Apache-2.0",
   "type": "module",

package/src/index.ts

@@ -7,7 +7,7 @@
  * `prodshape citations verify` to check.
  *
  * The product lane hosts the PDaC product workflow inside OpenSpec: the integration installs a
- * project-local `product` schema at `openspec/schemas/product/`, OpenSpec's official project
+ * project-local `product-change` schema at `openspec/schemas/product-change/`, OpenSpec's official project
  * extension surface, whose changes host a Product Change delta that `product-workflow.ts`
  * validates as an overlay and applies deterministically.
  *
@@ -29,11 +29,14 @@ import {
 } from '@prodshape/core';
 import { parse, stringify } from 'yaml';
 import {
-  loadProductSchemaAssets,
-  OPENSPEC_PRODUCT_SCHEMA_NAME,
-  OPENSPEC_PRODUCT_SCHEMA_RELATIVE,
-  PRODUCT_SCHEMA_MIN_OPENSPEC,
-} from './product-schema.js';
+  loadProductChangeSchemaAssets,
+  OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME,
+  OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE,
+  PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC,
+  loadProductRecoverySchemaAssets,
+  OPENSPEC_PRODUCT_RECOVERY_SCHEMA_NAME,
+  OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE,
+} from './product-change-schema.js';
 import { runCommand } from './process.js';
 import { envWithLocalBin, isOpenSpecWorkspace, pathExists } from './workspace.js';
 
@@ -44,12 +47,15 @@ export {
   openSpecProvider,
 } from './population.js';
 export {
-  loadProductSchemaAssets,
-  OPENSPEC_PRODUCT_SCHEMA_NAME,
-  OPENSPEC_PRODUCT_SCHEMA_RELATIVE,
-  PRODUCT_SCHEMA_MIN_OPENSPEC,
-} from './product-schema.js';
-export type { ProductSchemaAsset } from './product-schema.js';
+  loadProductChangeSchemaAssets,
+  OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME,
+  OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE,
+  PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC,
+  loadProductRecoverySchemaAssets,
+  OPENSPEC_PRODUCT_RECOVERY_SCHEMA_NAME,
+  OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE,
+} from './product-change-schema.js';
+export type { ProductChangeSchemaAsset } from './product-change-schema.js';
 export {
   applyOpenSpecProductChange,
   deriveDeliveryContext,
@@ -93,7 +99,7 @@ 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 — 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}`;
 
 /** The PDaC citation rules injected per artifact into openspec/config.yaml `rules:`. */
@@ -102,7 +108,7 @@ export const PDAC_RULES: Record<string, string[]> = {
     '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 — the backlog item behind it, if there is one — 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: [
@@ -192,8 +198,13 @@ export interface OpenSpecIntegrationMeta {
    * recorded digest, so ownership then rests on matching the current assets.
    */
   productSchema?: { name: string; requiresOpenspec: string; files: Record<string, string> };
+  recoverySchema?: { name: string; requiresOpenspec: string; files: Record<string, string> };
 }
 
+/** The pre-#227 schema location accepted only for safe, ownership-proven migration. */
+const LEGACY_OPENSPEC_PRODUCT_SCHEMA_NAME = 'product';
+const LEGACY_OPENSPEC_PRODUCT_SCHEMA_RELATIVE = 'openspec/schemas/product';
+
 /** The recorded product-schema files as path-to-digest, tolerating the earlier array shape. */
 function recordedProductSchemaFiles(
   meta: OpenSpecIntegrationMeta | null,
@@ -203,7 +214,9 @@ function recordedProductSchemaFiles(
   if (
     typeof record !== 'object' ||
     record === null ||
-    record.name !== OPENSPEC_PRODUCT_SCHEMA_NAME ||
+    (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(
@@ -213,12 +226,14 @@ function recordedProductSchemaFiles(
   const files = record.files as unknown;
   const validatePath = (file: unknown): file is string =>
     typeof file === 'string' &&
-    file.startsWith(`${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/`) &&
+    (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, '']));
@@ -227,7 +242,7 @@ function recordedProductSchemaFiles(
     const entries = Object.entries(files as Record<string, unknown>);
     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 (
@@ -242,6 +257,25 @@ function recordedProductSchemaFiles(
   throw new Error("'productSchema.files' must be a path-to-digest object or legacy path array");
 }
 
+function recordedRecoverySchemaFiles(
+  meta: OpenSpecIntegrationMeta | null,
+): Record<string, string> | undefined {
+  const record = meta?.recoverySchema;
+  if (!record) return undefined;
+  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;
+}
+
 /** Repository-relative paths used by this integration. */
 const CONFIG_RELATIVE = 'openspec/config.yaml';
 const META_RELATIVE = '.product/integrations/openspec.json';
@@ -683,7 +717,7 @@ export async function addOpenSpecIntegration(
     );
   }
 
-  // The OpenSpec product schema: managed files under openspec/schemas/product, the framework's
+  // The OpenSpec product schema: managed files under openspec/schemas/product-change, the framework's
   // official project-local schema surface. The files are version-independent data, so they are
   // installed regardless of the detected CLI version; whether the product workflow is USABLE on
   // this CLI is a separate, capability-specific report (`checkOpenSpecIntegration`), never a
@@ -694,10 +728,10 @@ export async function addOpenSpecIntegration(
   // still match the recorded digest. Any pre-existing unrecorded file is a collision, even when
   // byte-identical to the asset; on update a diverged managed file is preserved and reported, and
   // an obsolete still-managed file is removed only while its digest continues to match.
-  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: Record<string, string> = {};
   const schemaWrites: { relative: string; absolute: string; content: string }[] = [];
@@ -706,7 +740,7 @@ export async function addOpenSpecIntegration(
   const schemaPreserved: string[] = [];
   let schemaInstalledAnything = false;
   for (const asset of schemaAssets) {
-    const relative = `${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/${asset.relative}`;
+    const relative = `${OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE}/${asset.relative}`;
     const absolute = resolveInRepository(root, relative, 'the OpenSpec integration');
     const existing = (await pathExists(absolute)) ? await readFile(absolute, 'utf8') : null;
     const assetDigest = contentDigest(asset.content);
@@ -758,18 +792,18 @@ export async function addOpenSpecIntegration(
   }
   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 !== undefined || !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}.`,
+        ? `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.`,
       );
     }
   }
@@ -782,6 +816,49 @@ export async function addOpenSpecIntegration(
     );
   }
 
+  // The recovery workload has its own schema and ownership record. It is intentionally kept
+  // beside, rather than inside, product-change: recovery starts without an accepted baseline.
+  const recoveryAssets = await loadProductRecoverySchemaAssets();
+  const previousRecovery = recordedRecoverySchemaFiles(previousMeta);
+  const recoveryDigests: Record<string, string> = {};
+  const recoveryWrites: { relative: string; absolute: string; content: string }[] = [];
+  const recoveryCollisions: string[] = [];
+  for (const asset of recoveryAssets) {
+    const relative = `${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE}/${asset.relative}`;
+    const absolute = resolveInRepository(root, relative, 'the OpenSpec integration');
+    const existing = (await pathExists(absolute)) ? await readFile(absolute, 'utf8') : null;
+    const digest = contentDigest(asset.content);
+    const recorded = previousRecovery?.[relative];
+    if (existing === null) {
+      recoveryWrites.push({ relative, absolute, content: asset.content });
+      recoveryDigests[relative] = digest;
+    } else if (recorded === undefined) {
+      recoveryCollisions.push(relative);
+    } else if (existing === asset.content) {
+      recoveryDigests[relative] = digest;
+    } else if (recorded !== '' && contentDigest(existing) === recorded) {
+      recoveryWrites.push({ relative, absolute, content: asset.content });
+      recoveryDigests[relative] = digest;
+    } else {
+      recoveryDigests[relative] = recorded;
+      changes.push(
+        `Preserved hand-edited managed file ${relative}; 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 === undefined
+        ? `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).`,
+    );
+  }
+
   // `installedAt` records when this integration was first installed, and is preserved from here
   // on. Stamping a fresh timestamp on every invocation is what made a no-op `add` — and every
   // `integration update` — rewrite this file, so a command that reported "already up to date"
@@ -797,10 +874,15 @@ export async function addOpenSpecIntegration(
     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 ?? undefined);
@@ -831,6 +913,11 @@ export async function addOpenSpecIntegration(
       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);
     }
@@ -928,12 +1015,15 @@ export async function updateOpenSpecIntegration(
   root: string,
   options: { force?: boolean; dryRun?: boolean; warningsAsErrors?: boolean } = {},
 ): Promise<{ written: string[]; changes: string[] }> {
-  // `add` already re-merges idempotently; `force` ensures the metadata is refreshed even when
-  // the config content did not change.
+  // An existing metadata record is the compatibility verdict established during installation.
+  // Managed file reconciliation must remain usable in release jobs and repositories that no
+  // longer have OpenSpec on PATH; initial installation and explicit health checks still probe it.
+  const previousMeta = await readMeta(root);
   const result = await addOpenSpecIntegration(root, {
     force: true,
     dryRun: options.dryRun,
     warningsAsErrors: options.warningsAsErrors,
+    ...(previousMeta?.openspecVersion ? { cliVersion: previousMeta.openspecVersion } : {}),
   });
   return { written: result.written, changes: result.changes };
 }
@@ -1070,17 +1160,17 @@ export async function checkOpenSpecIntegration(root: string): Promise<{
   // files are inert data valid under any CLI, so a floor-violating CLI is not a managed-state
   // defect; it makes the product workflow UNAVAILABLE, stated as the check's verdict rather than
   // buried as a footnote, while the citation lane stays independently usable.
-  const schemaAssets = await loadProductSchemaAssets();
+  const schemaAssets = await loadProductChangeSchemaAssets();
   if (meta === null || meta.productSchema === undefined) {
     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: string[] = [];
     const unrecorded: string[] = [];
@@ -1090,7 +1180,7 @@ export async function checkOpenSpecIntegration(root: string): Promise<{
       .filter((relative) => !currentSchemaPaths.has(relative))
       .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     for (const asset of schemaAssets) {
-      const relative = `${OPENSPEC_PRODUCT_SCHEMA_RELATIVE}/${asset.relative}`;
+      const relative = `${OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE}/${asset.relative}`;
       const absolute = resolveInRepository(root, relative, 'the OpenSpec integration');
       const existing = (await pathExists(absolute)) ? await readFile(absolute, 'utf8') : null;
       const recordedDigest = recordedSchema[relative];
@@ -1149,21 +1239,59 @@ export async function checkOpenSpecIntegration(root: string): Promise<{
         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.`,
       });
     }
   }
 
+  // 6. Hosted recovery schema ownership is checked independently from product-change because
+  // the two workloads have different preconditions and may evolve on different cadences.
+  const recoveryAssets = await loadProductRecoverySchemaAssets();
+  const recoveryRecord = recordedRecoverySchemaFiles(meta);
+  if (recoveryRecord === undefined) {
+    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: string[] = [];
+    for (const asset of recoveryAssets) {
+      const relative = `${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE}/${asset.relative}`;
+      const absolute = resolveInRepository(root, relative, 'the OpenSpec integration');
+      const expected = recoveryRecord[relative];
+      if (expected === undefined) defects.push(`unrecorded: ${relative}`);
+      else if (!(await pathExists(absolute))) defects.push(`missing: ${relative}`);
+      else {
+        const actual = await readFile(absolute, 'utf8');
+        if (actual !== asset.content && contentDigest(actual) !== expected) {
+          defects.push(`hand-edited and preserved: ${relative}`);
+        } else if (actual !== asset.content) defects.push(`outdated managed content: ${relative}`);
+      }
+    }
+    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 };
 }
@@ -1330,8 +1458,8 @@ export async function removeOpenSpecIntegration(
   const recordedSchema = recordedProductSchemaFiles(previousMeta);
   if (recordedSchema !== undefined) {
     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,
       ]),
     );
@@ -1390,6 +1518,45 @@ export async function removeOpenSpecIntegration(
     }
   }
 
+  const recordedRecovery = recordedRecoverySchemaFiles(previousMeta);
+  if (recordedRecovery !== undefined) {
+    const recoveryAssets = new Map(
+      (await loadProductRecoverySchemaAssets()).map((asset) => [
+        `${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE}/${asset.relative}`,
+        asset.content,
+      ]),
+    );
+    for (const relative of Object.keys(recordedRecovery).sort()) {
+      const absolute = resolveInRepository(root, relative, 'the OpenSpec integration');
+      if (!(await pathExists(absolute))) continue;
+      const existing = await readFile(absolute, 'utf8');
+      const recordedDigest = recordedRecovery[relative];
+      const proven =
+        existing === recoveryAssets.get(relative) ||
+        (recordedDigest !== '' && contentDigest(existing) === recordedDigest);
+      if (!proven) {
+        preserved.push(relative);
+      } else {
+        if (!dryRun) await rm(absolute, { force: true });
+        removed.push(relative);
+      }
+    }
+    if (!dryRun) {
+      for (const relative of [
+        `${OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE}/templates`,
+        OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE,
+        'openspec/schemas',
+      ]) {
+        const absolute = resolveInRepository(root, relative, 'the OpenSpec integration');
+        try {
+          if ((await readdir(absolute)).length === 0) await rmdir(absolute);
+        } catch (error) {
+          if (!isNotFound(error)) throw error;
+        }
+      }
+    }
+  }
+
   // Remove metadata file.
   if (await pathExists(metaPath(root))) {
     if (!dryRun) {

package/src/{product-schema.ts → product-change-schema.ts}

@@ -1,8 +1,8 @@
 /**
- * The OpenSpec `product` schema shipped by this integration.
+ * The OpenSpec `product-change` schema shipped by this integration.
  *
  * The schema is a set of static assets (schema.yaml, templates, bridge scripts) bundled with the
- * package and installed into a consumer repository at `openspec/schemas/product/`. OpenSpec reads
+ * package and installed into a consumer repository at `openspec/schemas/product-change/`. OpenSpec reads
  * project-local schemas from that directory natively; installing files there uses the framework's
  * official extension surface, exactly as merging guidance into `openspec/config.yaml` does.
  *
@@ -14,10 +14,10 @@ import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
 
 /** The OpenSpec schema name (the directory key OpenSpec resolves). */
-export const OPENSPEC_PRODUCT_SCHEMA_NAME = 'product';
+export const OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME = 'product-change';
 
 /** The repository-relative directory the product schema is installed into. */
-export const OPENSPEC_PRODUCT_SCHEMA_RELATIVE = 'openspec/schemas/product';
+export const OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE = 'openspec/schemas/product-change';
 
 /**
  * The minimum OpenSpec CLI version the product workflow needs. Project-local schemas are far
@@ -28,17 +28,21 @@ export const OPENSPEC_PRODUCT_SCHEMA_RELATIVE = 'openspec/schemas/product';
  * files are inert data: the citation lane keeps working and the product workflow is reported
  * unavailable, never broken.
  */
-export const PRODUCT_SCHEMA_MIN_OPENSPEC = '1.7.0';
+export const PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC = '1.7.0';
+
+/** The separate hosted brownfield recovery workload. */
+export const OPENSPEC_PRODUCT_RECOVERY_SCHEMA_NAME = 'product-recovery';
+export const OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE = 'openspec/schemas/product-recovery';
 
 /** One bundled product-schema file: its path relative to the installed schema directory. */
-export interface ProductSchemaAsset {
+export interface ProductChangeSchemaAsset {
   relative: string;
   content: string;
 }
 
 /** The bundled asset directory, resolved from this module (both src/ and dist/ sit one level below the package root). */
 function assetsDir(): string {
-  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: string, prefix: string): Promise<string[]> {
@@ -59,10 +63,10 @@ async function collectFiles(dir: string, prefix: string): Promise<string[]> {
  * Load the bundled product-schema assets, sorted by relative path so installation, metadata and
  * comparison all see one deterministic order.
  */
-export async function loadProductSchemaAssets(): Promise<ProductSchemaAsset[]> {
+export async function loadProductChangeSchemaAssets(): Promise<ProductChangeSchemaAsset[]> {
   const dir = assetsDir();
   const relatives = await collectFiles(dir, '');
-  const assets: ProductSchemaAsset[] = [];
+  const assets: ProductChangeSchemaAsset[] = [];
   for (const relative of relatives.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))) {
     assets.push({
       relative,
@@ -71,3 +75,19 @@ export async function loadProductSchemaAssets(): Promise<ProductSchemaAsset[]> {
   }
   return assets;
 }
+
+/** Load the bundled recovery schema assets using the same deterministic asset contract. */
+export async function loadProductRecoverySchemaAssets(): Promise<ProductChangeSchemaAsset[]> {
+  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 (relative) => ({
+        relative,
+        content: await readFile(join(dir, ...relative.split('/')), 'utf8'),
+      })),
+  );
+}