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

package/src/product-workflow.ts

@@ -1,8 +1,8 @@
 /**
  * The deterministic rails of the OpenSpec-hosted PDaC product workflow.
  *
- * An OpenSpec change created with the `product` schema hosts a PDaC Product Change at
- * `openspec/changes/<name>/product/` (change.md plus proposed/**, the normative delta format).
+ * An OpenSpec change created with the `product-change` schema hosts a PDaC Product Change at
+ * `openspec/changes/<name>/product-change/` (change.md plus proposed/**, the normative delta format).
  * OpenSpec owns the workflow orchestration (`/opsx:new`, `/opsx:continue`, `/opsx:apply`,
  * `/opsx:archive`); this module owns what OpenSpec cannot provide: reading the accepted model,
  * compiling the semantic graph in memory, validating the hosted delta as an overlay on the
@@ -31,18 +31,17 @@ import { join } from 'node: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';
 import type {
@@ -55,11 +54,11 @@ import type {
   ProductGraph,
   ProductRepository,
 } from '@prodshape/core';
-import { OPENSPEC_PRODUCT_SCHEMA_NAME } from './product-schema.js';
+import { OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME } from './product-change-schema.js';
 import { pathExists } from './workspace.js';
 
 /** The subdirectory of an OpenSpec change that hosts the PDaC Product Change delta. */
-export const OPENSPEC_PRODUCT_SUBDIR = 'product';
+export const OPENSPEC_PRODUCT_SUBDIR = 'product-change';
 
 /** OpenSpec 1.11's change-id grammar (`isKebabId`): one folder-safe path segment. */
 const OPENSPEC_CHANGE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
@@ -101,7 +100,7 @@ export async function inspectProductModel(root: string): Promise<ProductModelIns
 export interface OpenSpecProductChangeRef {
   /** The OpenSpec change name (the directory under openspec/changes/). */
   name: string;
-  /** Absolute path of the hosted PDaC change directory (…/<name>/product). */
+  /** Absolute path of the hosted PDaC change directory (…/<name>/product-change). */
   dir: string;
   /** Repository-relative POSIX path of the hosted change.md. */
   file: string;
@@ -171,7 +170,7 @@ function openSpecChangeMetadataProblem(parsed: unknown): string | undefined {
 
 /**
  * Read the schema a change is pinned to. OpenSpec records it in the change's `.openspec.yaml`
- * (`openspec new change <name> --schema product` writes it), and the hosted product rail treats
+ * (`openspec new change <name> --schema product-change` writes it), and the hosted product rail treats
  * that pin as load-bearing: OpenSpec selects the workflow, so a change is a product change
  * because its container says so, never because a `product/` directory happens to exist.
  */
@@ -198,7 +197,7 @@ function hostedSchemaPinError(
 ): Error {
   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(
@@ -207,8 +206,8 @@ function hostedSchemaPinError(
 }
 
 /**
- * List the OpenSpec changes that host a PDaC Product Change: pinned to `schema: product` in
- * `.openspec.yaml` AND carrying `product/change.md`. The OpenSpec archive is history and is never
+ * List the OpenSpec changes that host a PDaC Product Change: pinned to `schema: product-change` in
+ * `.openspec.yaml` AND carrying `product-change/change.md`. The OpenSpec archive is history and is never
  * listed; a change without a product delta (for example one whose honest intent verdict was "no
  * product delta") is not a product change; and a change pinned to another schema is not one
  * either, whatever directories it contains, so it never enters the product rail or its
@@ -237,7 +236,7 @@ export async function listOpenSpecProductChanges(
     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,
@@ -273,7 +272,7 @@ async function loadHostedChange(
     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}).`,
     );
   }
   // The schema pin is load-bearing and fails closed: without a readable pin naming the product
@@ -282,9 +281,9 @@ async function loadHostedChange(
   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);
@@ -349,20 +348,21 @@ export async function validateOpenSpecProductChange(
     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,
   };
 }
 
@@ -373,7 +373,7 @@ function hostedName(root: string, change: LoadedChange): string | undefined {
   const relative = normalizedDir.startsWith(normalizedRoot)
     ? normalizedDir.slice(normalizedRoot.length).replace(/^\//, '')
     : normalizedDir;
-  const match = relative.match(/^openspec\/changes\/([^/]+)\/product$/);
+  const match = relative.match(/^openspec\/changes\/([^/]+)\/product-change$/);
   return match?.[1];
 }
 
@@ -419,7 +419,13 @@ export async function applyOpenSpecProductChange(
     all.find((candidate) => hostedName(root, candidate) === changeName) ??
     (await loadHostedChange(root, repo, changeName));
 
-  const validation = validateChange(change, baseline.artifacts, all);
+  const hosted = validateHostedProductChange(
+    repo,
+    baseline.artifacts,
+    change,
+    all,
+    baseline.diagnostics,
+  );
   // Everything capable of making the resulting model invalid blocks BEFORE any write:
   // configuration diagnostics, the baseline's own load and per-document diagnostics, the change's
   // diagnostics and the full overlay revalidation. The overlay pass alone is not enough, because
@@ -427,24 +433,13 @@ export async function applyOpenSpecProductChange(
   // body-section defects) are load-time diagnostics that graph-level revalidation never re-emits;
   // omitting them let apply write into a model whose fresh validation then failed, violating the
   // resulting-model obligation. Refusal happens with the working tree byte-identical.
-  const overlayErrors = blockingDiagnostics(
-    sortDiagnostics(
-      dedupeDiagnostics([
-        ...repo.configDiagnostics,
-        ...baseline.diagnostics,
-        ...validation.diagnostics,
-      ]),
-    ),
-    repo.config.validation['warnings-as-errors'],
-  );
-
-  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: ApplyPlan = {
     ...rawPlan,

package/assets/openspec-product-schema/templates/change.md

@@ -1,49 +0,0 @@
----
-id: CHG-EXAMPLE-001
-type: product-change
-title: Example product change
-status: draft
-base-revision: '3f2a91c'
-operations:
-  add:
-    - FR-EXAMPLE-001
-  modify:
-    - UC-EXAMPLE-001
-  remove: []
----
-
-This file lives at `product/change.md` inside the OpenSpec change directory, and the proposed future state lives beside it under `product/proposed/**`, laid out exactly as it will live in `docs/product/model` with files named by lowercase id.
-
-This manifest and every artifact under `product/proposed/**` are Product Definition content, not consumer documents. Do not add `pdac-scope` declarations or PDaC citations here. Proposed artifacts express their internal connections through typed PDaC relationships; citations remain in `proposal.md` and other documents that consume the accepted model.
-
-Every ID under `operations.add` and `operations.modify` needs a complete proposed artifact under `product/proposed/`. Author each artifact from its current PDaC template (`prodshape template <kind>`). Set `base-revision` to the baseline commit this change was authored against, quoted so YAML reads an all-digit revision as a string.
-
-Leave `status: draft` while authoring; `status: approved` is the apply-authorised protocol state and setting it is the caller's authorisation act, outside this workflow. Apply materializes the proposal into the accepted model on a working branch; it never archives this change, and a pull-request merge accepts the resulting baseline. Product Change status never records implementation, verification, release or deployment.
-
-## Problem
-
-What is wrong or missing in the current Product Definition? State the problem, not the solution.
-
-## Intended Product Outcome
-
-What the Product Definition says once this change is accepted. Describe the destination, not the steps.
-
-## Rationale
-
-Why this outcome, and why now. Record the reasoning a future reader would otherwise have to reconstruct.
-
-## Affected Product Areas
-
-Which parts of the product this change touches, in product language rather than file paths.
-
-## Open Questions
-
-Unresolved questions that need a decision before the change can be authorised. If answering a question could produce materially different product behaviour, scope, policy or acceptance, ask the product owner and stop: do not complete this delta or select an answer on the user's behalf. Write `None.` only after every product-semantic question in both the intent and this manifest has been resolved.
-
-## Product Acceptance
-
-How a reviewer recognises that the accepted definition expresses the intended outcome.
-
-## Out of Scope
-
-What this change explicitly does not touch, including delivery, technical design and implementation.