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

package/README.md

@@ -2,7 +2,7 @@
 
 OpenSpec integration for Product Definition as Code (PDaC), in two lanes: a citation lane that grounds OpenSpec's spec-driven delivery workflow in the accepted product model, and a product lane that hosts the PDaC product workflow inside OpenSpec itself.
 
-Both lanes write only official OpenSpec surfaces (`openspec/config.yaml`, `openspec/schemas/product/`) plus ProductShape's own integration metadata (`.product/integrations/openspec.json`). The integration never patches OpenSpec-generated commands or skills, never modifies OpenSpec's built-in schemas, and never writes into a native spec-driven change's documents. Every write is byte-gated and ownership-proven per file: metadata paths are validated and confined to `openspec/schemas/product/`; `prodshape integration add openspec` collides on every pre-existing unrecorded target, even when byte-identical; `update` replaces or removes only content whose recorded digest still proves ownership, including obsolete assets; and `remove` deletes only recorded, proven-managed files while preserving and reporting unrecorded or hand-edited ones. With no recorded product schema it touches nothing under `openspec/schemas/`. Dry runs report exactly what the real operation would do.
+Both lanes write only official OpenSpec surfaces (`openspec/config.yaml`, `openspec/schemas/product-change/`, and `openspec/schemas/product-recovery/`) plus ProductShape's own integration metadata (`.product/integrations/openspec.json`). The integration never patches OpenSpec-generated commands or skills, never modifies OpenSpec's built-in schemas, and never writes into a native spec-driven change's documents. Every write is byte-gated and ownership-proven per file; `update` replaces or removes only content whose recorded digest still proves ownership, while `remove` preserves unrecorded or hand-edited files. Dry runs report exactly what the real operation would do.
 
 ## The citation lane (delivery)
 
@@ -10,16 +10,18 @@ The integration merges PDaC authority context and citation rules into `openspec/
 
 ## The product lane (the hosted product workflow)
 
-The integration installs a project-local OpenSpec schema named `product` at `openspec/schemas/product/`. An OpenSpec change created with that schema hosts a PDaC Product Change: the normative semantic delta (`product/change.md` plus `product/proposed/**`) against the accepted model in `docs/product/model`, which stays the only source of product truth.
+The integration installs a project-local OpenSpec schema named `product-change` at `openspec/schemas/product-change/`. An OpenSpec change created with that schema hosts a PDaC Product Change: the normative semantic delta (`product-change/change.md` plus `product-change/proposed/**`) against the accepted model in `docs/product/model`, which stays the only source of product truth.
 
-The schema pin is a load-bearing, enforced invariant: the rail accepts only one folder-safe OpenSpec 1.11 change name and validates the complete OpenSpec 1.11 metadata shape in `.openspec.yaml`, not merely the presence of a schema string. It treats a change as a product change only when that valid metadata pins `schema: product`. A change pinned to another schema never lists, validates, applies or enters concurrency, however product-shaped its contents look. A product-shaped container with missing or malformed metadata stops listing and concurrency with a clear error instead of disappearing from the live-change set.
+For brownfield systems without an accepted baseline, the integration also installs the independent `product-recovery` schema at `openspec/schemas/product-recovery/`. Use `/opsx:new <name> --schema product-recovery`, confirm `recovery/brief.md`, and repeat `/opsx:continue` for bounded evidence rounds. Recovery state and the draft `CHG-INITIAL` remain inside the OpenSpec change container; they never write `.product/generated/recovery/` or `docs/product/changes/active/`. A completed recovery may produce a candidate baseline or an honest insufficient-evidence outcome. Only a human-approved candidate baseline can delegate to the existing Product Change apply rail, and archive remains separate.
+
+The schema pin is a load-bearing, enforced invariant: the rail accepts only one folder-safe OpenSpec 1.11 change name and validates the complete OpenSpec 1.11 metadata shape in `.openspec.yaml`, not merely the presence of a schema string. It treats a change as a product change only when that valid metadata pins `schema: product-change`. A change pinned to another schema never lists, validates, applies or enters concurrency, however product-shaped its contents look. A product-shaped container with missing or malformed metadata stops listing and concurrency with a clear error instead of disappearing from the live-change set.
 
 The primary workflow is OpenSpec's own:
 
 ```text
-/opsx:new <change> --schema product
+/opsx:new <change> --schema product-change
         |
-/opsx:continue (or /opsx:ff)      authors proposal.md, then product/change.md + product/proposed/**
+/opsx:continue (or /opsx:ff)      authors proposal.md, then product-change/change.md + product-change/proposed/**
         |
 /opsx:apply <change>              follows the schema's apply instruction
         |
@@ -29,14 +31,14 @@ The primary workflow is OpenSpec's own:
 Apply and archive are separate lifecycle operations. The schema's apply instruction delegates the deterministic write to this package's apply rail through the installed bridge script:
 
 ```text
-node openspec/schemas/product/scripts/product-apply.mjs --change <name> [--dry-run]
+node openspec/schemas/product-change/scripts/product-apply.mjs --change <name> [--dry-run]
 ```
 
 The bridge resolves the locally installed `@prodshape/integration-openspec` and calls `applyOpenSpecProductChange`, which re-reads the accepted model and revalidates everything at apply time: the configuration, the baseline itself (including per-document load diagnostics of artifacts the change never touches) and the hosted delta as an overlay; a prior validate call is never trusted. Any blocking diagnostic refuses before any write, with the model and the change container byte-identical. It enforces base-revision drift (PRODUCT027) and the apply-authorised state (PRODUCT028, whose hosted message states the protocol requirement without pretending to verify the actor), writes the delta into the model named by lowercase id, reports the product diff computed from the result, and flips the hosted change.md status to applied in place. It never commits and never archives; `openspec archive` moves the change container afterwards and never touches the model. A preflight bridge exists beside it (`product-validate.mjs`) for explicit overlay validation at any point.
 
 Validation is mandatory; authorisation policy is outside the deterministic rail. `status: approved` in the hosted change.md is the apply-authorised protocol state. ProductShape's accepted policy requires human product approval before that state is recorded; the integration verifies the state but cannot identify or judge the actor, and it never performs the transition. Merging the resulting baseline also remains a human decision.
 
-Product-semantic clarification happens before the delta. While authoring the intent, the schema asks the agent to identify wording that admits materially different observable outcomes, present those alternatives to the user and stop. An unresolved decision must remain visible under `Open Questions for the Product Owner`; the agent must not choose an outcome, author the delta or seek approval merely to advance the artifact graph. The deterministic rail validates structure and semantics it can prove, but it cannot infer that a human-facing request was ambiguous. `proposal.md` cites the accepted model it consumes; `product/change.md` and `product/proposed/**` carry no citations or scope declarations, and only the proposed artifacts can be materialized into the accepted model.
+Product-semantic clarification happens before the delta. While authoring the intent, the schema asks the agent to identify wording that admits materially different observable outcomes, present those alternatives to the user and stop. An unresolved decision must remain visible under `Open Questions for the Product Owner`; the agent must not choose an outcome, author the delta or seek approval merely to advance the artifact graph. The deterministic rail validates structure and semantics it can prove, but it cannot infer that a human-facing request was ambiguous. `proposal.md` cites the accepted model it consumes; `product-change/change.md` and `product-change/proposed/**` carry no citations or scope declarations, and only the proposed artifacts can be materialized into the accepted model.
 
 ### Requirements
 
@@ -51,7 +53,7 @@ The deterministic rails are exported for wrappers, tests and custom callers; the
 ```ts
 import {
   inspectProductModel, // accepted model + in-memory graph + diagnostics
-  listOpenSpecProductChanges, // OpenSpec changes hosting product/change.md
+  listOpenSpecProductChanges, // OpenSpec changes hosting product-change/change.md
   loadOpenSpecProductChange,
   validateOpenSpecProductChange, // overlay validation; concurrency spans both containers
   applyOpenSpecProductChange, // revalidates at apply time; fail closed; never archives
@@ -62,3 +64,5 @@ import {
 Concurrency (PRODUCT025) spans both change containers: a hosted OpenSpec product change and a native change under `docs/product/changes/active` touching the same artifact report against each other.
 
 The citation-lane surface (`addOpenSpecIntegration`, `updateOpenSpecIntegration`, `checkOpenSpecIntegration`, `removeOpenSpecIntegration`, `bootstrapOpenSpecWorkspace`, the population provider) is unchanged and documented in the module source.
+
+`addOpenSpecIntegration` and `checkOpenSpecIntegration` detect the OpenSpec CLI because they establish or verify the recorded compatibility verdict. `updateOpenSpecIntegration` uses that verdict from `.product/integrations/openspec.json`, so managed configuration and schema ownership reconciliation remains available when OpenSpec is not on `PATH`; an update without existing integration metadata follows the same detection requirement as a first installation.

package/assets/{openspec-product-schema → openspec-product-change-schema}/schema.yaml

@@ -1,7 +1,7 @@
 # MANAGED FILE. Installed by `prodshape integration add openspec` and regenerated by
 # `prodshape integration update`. Hand edits are reported by `prodshape doctor` and replaced
 # on the next update; remove the integration to take the schema out.
-name: product
+name: product-change
 version: 1
 description: >-
   PDaC product workflow hosted in OpenSpec: requested product intent becomes a Product Change delta against the accepted model in docs/product/model, deterministically validated as an overlay, then applied by the PDaC integration only for a change in the apply-authorised state. Requires OpenSpec >= 1.7.0. This schema changes product meaning only; implementation work belongs to a separate spec-driven change.
@@ -13,6 +13,13 @@ artifacts:
     instruction: |
       Capture WHY the product definition should change, before any delta exists.
 
+      Run a proportional integrity pass before authoring the first delta. Show a small prioritised
+      report: for each changed or proposed node, name the neighbouring candidate, relationship,
+      impact polarity and the mechanical reason it merits review. Classify each candidate as
+      affected, checked and unaffected, or uncertain. This graph evidence is assistance, never
+      authority: it must not expand scope or modify an artifact. Explain why relevant categories
+      and neighbours were left unchanged.
+
       Ground the intent in the accepted model:
       1. Read the accepted Product Definition (docs/product/model unless .product/config.yaml moves product-root).
          Never treat proposals, archived changes or OpenSpec documents as product truth.
@@ -39,20 +46,33 @@ artifacts:
       delivery-only work), record that verdict under the "No product delta" heading and STOP: do not
       author a delta artifact and do not invent product change to satisfy the workflow. Otherwise state
       the intended product outcome in product language, not implementation language.
+
+      Keep proposal.md as resumable working memory: record the current queue, checked-and-excluded
+      candidates, recommendations, parked items, parked questions and verbatim human answers. Ask exactly one
+      question at a time, highest product risk first. A user may stop, park a question, or place a
+      possible gap explicitly out of scope. The readiness conclusion must say whether no material
+      product decisions remain unresolved, named decisions are required, or named possible gaps
+      remain and may be refined now or consciously placed out of scope.
+      Record checked and excluded candidates in the proposal even when they need no artifact.
     requires: []
 
   - id: delta
-    generates: 'product/**/*.md'
+    generates: 'product-change/**/*.md'
     description: The PDaC Product Change delta, change.md plus the complete proposed future state
     template: change.md
     instruction: |
-      Author the PDaC Product Change under product/ in this change directory: product/change.md plus
-      product/proposed/** holding the COMPLETE future state of every artifact the change adds or
+      Author the PDaC Product Change under product/ in this change directory: product-change/change.md plus
+      product-change/proposed/** holding the COMPLETE future state of every artifact the change adds or
       modifies, laid out exactly as it will live in the model (actors/, journeys/, use-cases/,
       business-rules/, behaviours/, domain/terms/, domain/bounded-contexts/, requirements/functional/,
       requirements/quality/, requirements/constraints/), each file named <lowercase-id>.md.
 
       Rules that make the delta valid:
+      - Perform the proportional integrity pass again before the first delta, after a material
+        widening of intent, when the delta begins to modify additional graph nodes, whenever the
+        user explicitly requests another refinement pass, and immediately before approval.
+        Editorial corrections do not require a new whole pass. Recompute the explained graph
+        candidates; do not expand scope or modify a neighbour automatically.
       - Re-read the intent's "Open Questions for the Product Owner" before writing. Do not author or
         complete the delta while any product-semantic question remains unresolved: ask the user and stop.
         Never choose a product outcome on the user's behalf. Carry the user's answer into one unambiguous
@@ -62,14 +82,14 @@ artifacts:
         and operations with all three keys add, modify and remove. The body carries seven sections in
         order: Problem, Intended Product Outcome, Rationale, Affected Product Areas, Open Questions,
         Product Acceptance, Out of Scope.
-      - product/change.md is a change manifest, not a consumer document. Never add PDaC citations or a
-        pdac-scope declaration to it or to product/proposed/**. Citations belong in proposal.md and other
+      - product-change/change.md is a change manifest, not a consumer document. Never add PDaC citations or a
+        pdac-scope declaration to it or to product-change/proposed/**. Citations belong in proposal.md and other
         documents that consume the accepted model; proposed artifacts use typed PDaC relationships.
       - Preserve stable IDs: evolve an existing artifact by listing its EXISTING id under
         operations.modify, never by adding a near duplicate under a new id. Create only the artifacts
         the intent requires.
       - Every id in operations.add and operations.modify has a complete proposed artifact under
-        product/proposed/; nothing else appears there. Removals list existing ids and ship no files.
+        product-change/proposed/; nothing else appears there. Removals list existing ids and ship no files.
       - Use the exact current PDaC formats. `prodshape template <kind>` prints the authoring template
         for every kind (actor, journey, use-case, business-rule, domain-term, bounded-context,
         functional-requirement, quality-requirement, constraint, structured-behaviour); it resolves the
@@ -87,8 +107,16 @@ artifacts:
         deterministic apply of this change.
 
       Preflight is available at any time:
-      `node openspec/schemas/product/scripts/product-validate.mjs --change <change-name>` validates the
+      `node openspec/schemas/product-change/scripts/product-validate.mjs --change <change-name>` validates the
       accepted baseline plus this delta as an overlay without touching either.
+
+      The semantic requests "refine", "review" and "challenge this product change", and the
+      explicit `/product:refine <change>` command, resume this same OpenSpec product-change
+      container. The refine adapter may update proposal.md, change.md and proposed artifacts, but
+      it must never approve, apply or archive. If no change is identifiable, ask the user to select
+      one or create one through the normal OpenSpec workflow; do not create a second lifecycle.
+      This is the same OpenSpec change, not a new refinement workflow.
+      This is the same OpenSpec change, not a new refinement workflow.
     requires:
       - intent
 
@@ -99,14 +127,17 @@ apply:
     Apply materializes the approved delta into docs/product/model. It is never implicit, never a
     commit and never an archive.
 
-    1. Confirm the change is in the apply-authorised state: product/change.md carries
+    1. Confirm the change is in the apply-authorised state: product-change/change.md carries
        status: approved. That protocol state is required for apply (PRODUCT028 otherwise); the
        integration checks only that protocol state. ProductShape's accepted policy requires human
        product approval; neither this workflow nor the integration grants, infers or judges it.
        Before asking for or recording that state, confirm there are no unresolved product-semantic questions
        in either the intent or the delta. `status: approved` must not be recorded merely to make apply proceed.
+       Immediately before asking for approval, run the proportional integrity pass again, record
+       the report and distinguish unresolved decisions from optional further depth. Parked decisions
+       keep the change unready; consciously excluded gaps must be named under Out of Scope.
     2. Run the deterministic apply through the PDaC integration, dry run first:
-       `node openspec/schemas/product/scripts/product-apply.mjs --change <change-name> --dry-run`
+       `node openspec/schemas/product-change/scripts/product-apply.mjs --change <change-name> --dry-run`
        then without --dry-run. The script resolves the locally installed
        @prodshape/integration-openspec and calls its apply rail, which re-reads the accepted model,
        revalidates this delta as an overlay at apply time, refuses on any blocking diagnostic with

package/assets/{openspec-product-schema → openspec-product-change-schema}/scripts/product-apply.mjs

@@ -10,13 +10,13 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import process from 'node:process';
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
-// openspec/schemas/product/scripts sits four levels below the repository root.
+// openspec/schemas/product-change/scripts sits four levels below the repository root.
 const defaultRoot = resolve(scriptDir, '..', '..', '..', '..');
 
 function usage(message) {
   console.error(message);
   console.error(
-    'Usage: node openspec/schemas/product/scripts/product-apply.mjs --change <name> [--dry-run] [--root <dir>]',
+    'Usage: node openspec/schemas/product-change/scripts/product-apply.mjs --change <name> [--dry-run] [--root <dir>]',
   );
   process.exit(2);
 }

package/assets/{openspec-product-schema → openspec-product-change-schema}/scripts/product-validate.mjs

@@ -8,13 +8,13 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import process from 'node:process';
 
 const scriptDir = dirname(fileURLToPath(import.meta.url));
-// openspec/schemas/product/scripts sits four levels below the repository root.
+// openspec/schemas/product-change/scripts sits four levels below the repository root.
 const defaultRoot = resolve(scriptDir, '..', '..', '..', '..');
 
 function usage(message) {
   console.error(message);
   console.error(
-    'Usage: node openspec/schemas/product/scripts/product-validate.mjs --change <name> [--root <dir>]',
+    'Usage: node openspec/schemas/product-change/scripts/product-validate.mjs --change <name> [--root <dir>]',
   );
   process.exit(2);
 }

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

@@ -0,0 +1,51 @@
+---
+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/change.md` inside the OpenSpec change directory, and the proposed future state lives beside it under `product-change/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-change/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-change/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.
+
+Distil each accepted decision that explains the delta here, next to the relevant edit. Preserve the human's answer verbatim; do not replace it with an interpretation.
+
+## Affected Product Areas
+
+Which parts of the product this change touches, in product language rather than file paths.
+
+## Open Questions
+
+Only genuinely unresolved decisions remain here. Include parked questions and why they are parked. If answering a question could produce materially different product behaviour, ask exactly one question at a time 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 consciously excluded gaps, delivery, technical design and implementation. A graph neighbour checked and found unaffected belongs here as an explained exclusion, not as a silent omission.

package/assets/{openspec-product-schema → openspec-product-change-schema}/templates/proposal.md

@@ -20,6 +20,18 @@ Every accepted artifact this intent depends on, alters or contradicts. One line
 
 Artifacts inspected through the graph (impact, relationships) and judged out of scope, each with the one-line reason. Write `None.` when the impact list already covers everything inspected.
 
+## Clarification Report
+
+Before interviewing, record a small, prioritised integrity pass. For each changed or proposed node, list the neighbouring candidate, relationship, impact polarity and the mechanical reason it merits review. Classify each candidate as affected, checked and unaffected, or uncertain. The graph is evidence for review, never authority: it must not expand scope or modify an artifact. Explain why relevant categories and neighbours were left unchanged.
+
+Repeat the pass before the first delta, after a material widening, when new graph nodes enter the delta, after an explicit `/product:refine` request, and immediately before approval. Editorial corrections do not require a new whole pass. A small clear change may have no questions; a large coherent outcome may remain one change.
+
+## Refinement pass
+
+Read the existing OpenSpec change before each sitting and reconstruct its state without chat history. Keep this proposal as working memory across sittings. Record the current queue, evidence, checked and excluded candidates, recommendations, parked questions and verbatim human answers. Ask exactly one question at a time, highest product risk first. A user may stop, park a question, or explicitly place a gap out of scope. Do not present the change as ready while a parked decision remains unresolved.
+
+The readiness conclusion must distinguish one of: no material product decisions remain unresolved; named decisions are required before completion or approval; or named possible gaps remain and may be refined now or consciously placed out of scope.
+
 ## No Product Delta
 
 Only when the honest verdict is that this request changes no product meaning: state that verdict and the reason, and stop the workflow here (no delta artifact follows). Delete this section otherwise.

package/assets/openspec-product-recovery-schema/schema.yaml

@@ -0,0 +1,40 @@
+# MANAGED FILE. Installed by `prodshape integration add openspec`.
+name: product-recovery
+version: 1
+description: >-
+  PDaC brownfield recovery hosted in OpenSpec. Evidence is processed in bounded, resumable rounds and converges on a draft CHG-INITIAL Product Change.
+artifacts:
+  - id: brief
+    generates: recovery/brief.md
+    description: Confirmed recovery scope, evidence authority and batch policy
+    template: brief.md
+    instruction: |
+      Agree this brief with the human before reading evidence. The brief is the
+      authority for roots, include/exclude/forbidden patterns, ordered tiers,
+      batch size and explicitly authorised external sources.
+    requires: []
+  - id: recovery-outcome
+    generates: recovery/report.md
+    description: Iterative evidence recovery report and hosted CHG-INITIAL draft
+    template: report.md
+    instruction: |
+      Repeat `/opsx:continue` for one bounded round at a time. Re-inventory and
+      re-hash first, stop on drift, then process at most the configured batch.
+      Use the deterministic ProductShape recovery capabilities for state changes;
+      never edit state files manually. Keep recovery/** and product-change/**
+      inside this OpenSpec change container. Distinguish observed evidence from
+      inference, preserve provenance and confidence, record contradictions as
+      questions, and finish either with a defensible candidate baseline or an
+      explicit insufficient-evidence report. Do not approve or apply.
+    requires:
+      - brief
+apply:
+  requires:
+    - recovery-outcome
+  instruction: |
+    Apply is available only for a complete candidate-baseline outcome with a
+    human-approved CHG-INITIAL in product-change/change.md. Revalidate fresh
+    evidence, recovery completion, model drift and the complete overlay, then
+    delegate to the existing Product Change apply rail. An insufficient-evidence
+    outcome reports that there is nothing to apply. Never commit or archive;
+    `/opsx:archive` remains a separate action.

package/assets/openspec-product-recovery-schema/templates/brief.md

@@ -0,0 +1,22 @@
+# Recovery brief
+
+```yaml
+schema: product-definition-as-code/recovery-brief/v1alpha1
+roots: [.]
+include: ['**/*']
+exclude: []
+forbidden: ['**/.env', '**/.env.*', '**/*.pem', '**/*.key', '**/secrets/**']
+ignore: []
+languages: []
+tiers: []
+batch-size: 10
+external-sources: []
+```
+
+## Product scope
+
+## Evidence authority and secondary-evidence policy
+
+## Known vocabulary, actors and contradictions
+
+## Areas requiring human confirmation

package/assets/openspec-product-recovery-schema/templates/report.md

@@ -0,0 +1,15 @@
+# Recovery outcome
+
+This artifact is resumable working memory. It is not accepted product truth.
+
+## Progress and next bounded batch
+
+## Observed evidence and inferred intent
+
+## Candidates and provenance
+
+## Questions, contradictions and leads
+
+## Outcome
+
+State either `Candidate baseline produced` or `Insufficient evidence`. A candidate baseline must reference `product-change/change.md` and its proposed artifacts. An insufficient outcome must contain no invented or empty delta.

package/dist/index.d.ts

@@ -32,9 +32,9 @@ declare function enumerateOpenSpecDocuments(repoRoot: string, options?: Enumerat
 declare const openSpecProvider: SddIntegrationProvider;
 
 /** The OpenSpec schema name (the directory key OpenSpec resolves). */
-declare const OPENSPEC_PRODUCT_SCHEMA_NAME = "product";
+declare const OPENSPEC_PRODUCT_CHANGE_SCHEMA_NAME = "product-change";
 /** The repository-relative directory the product schema is installed into. */
-declare const OPENSPEC_PRODUCT_SCHEMA_RELATIVE = "openspec/schemas/product";
+declare const OPENSPEC_PRODUCT_CHANGE_SCHEMA_RELATIVE = "openspec/schemas/product-change";
 /**
  * The minimum OpenSpec CLI version the product workflow needs. Project-local schemas are far
  * older, but three 1.7.0 behaviours are load-bearing: `openspec new change` records
@@ -44,9 +44,12 @@ declare 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.
  */
-declare const PRODUCT_SCHEMA_MIN_OPENSPEC = "1.7.0";
+declare const PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC = "1.7.0";
+/** The separate hosted brownfield recovery workload. */
+declare const OPENSPEC_PRODUCT_RECOVERY_SCHEMA_NAME = "product-recovery";
+declare const OPENSPEC_PRODUCT_RECOVERY_SCHEMA_RELATIVE = "openspec/schemas/product-recovery";
 /** One bundled product-schema file: its path relative to the installed schema directory. */
-interface ProductSchemaAsset {
+interface ProductChangeSchemaAsset {
     relative: string;
     content: string;
 }
@@ -54,10 +57,12 @@ interface ProductSchemaAsset {
  * Load the bundled product-schema assets, sorted by relative path so installation, metadata and
  * comparison all see one deterministic order.
  */
-declare function loadProductSchemaAssets(): Promise<ProductSchemaAsset[]>;
+declare function loadProductChangeSchemaAssets(): Promise<ProductChangeSchemaAsset[]>;
+/** Load the bundled recovery schema assets using the same deterministic asset contract. */
+declare function loadProductRecoverySchemaAssets(): Promise<ProductChangeSchemaAsset[]>;
 
 /** The subdirectory of an OpenSpec change that hosts the PDaC Product Change delta. */
-declare const OPENSPEC_PRODUCT_SUBDIR = "product";
+declare const OPENSPEC_PRODUCT_SUBDIR = "product-change";
 /** The accepted product model, read directly from disk and validated, with its in-memory graph. */
 interface ProductModelInspection {
     repo: ProductRepository;
@@ -76,14 +81,14 @@ declare function inspectProductModel(root: string): Promise<ProductModelInspecti
 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;
 }
 /**
- * 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
@@ -178,7 +183,7 @@ declare const MIN_SUPPORTED_OPENSPEC = "1.0.0";
  */
 declare const OPENSPEC_NPX_SPEC = "@fission-ai/openspec@1";
 /** The PDaC authority context block injected into openspec/config.yaml `context:`. */
-declare const PDAC_CONTEXT_BLOCK = "<!-- pdac:context begin -->\nThis repository uses Product Definition as Code (PDaC). The canonical product definition lives in docs/product/model (actors, journeys, use cases, business rules, domain terms, bounded contexts, structured behaviours, and functional, quality and constraint requirements). OpenSpec artifacts consume it and are never a second source of truth.\nA citation binds consumer text to a canonical artifact: it records the artifact id, a sha256 content digest and an optional verification scenario anchor. Verification reports one status per citation: current, stale, tampered or unresolved.\nTo 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.\nTo 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.\nEvery 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.\nThe 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.\n<!-- pdac:context end -->";
+declare const PDAC_CONTEXT_BLOCK = "<!-- pdac:context begin -->\nThis repository uses Product Definition as Code (PDaC). The canonical product definition lives in docs/product/model (actors, journeys, use cases, business rules, domain terms, bounded contexts, structured behaviours, and functional, quality and constraint requirements). OpenSpec artifacts consume it and are never a second source of truth.\nA citation binds consumer text to a canonical artifact: it records the artifact id, a sha256 content digest and an optional verification scenario anchor. Verification reports one status per citation: current, stale, tampered or unresolved.\nTo 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.\nTo 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.\nEvery 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.\nThe 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.\n<!-- pdac:context end -->";
 /** The PDaC citation rules injected per artifact into openspec/config.yaml `rules:`. */
 declare const PDAC_RULES: Record<string, string[]>;
 /** The PDaC operation guidance injected into openspec/config.yaml `operations:`. */
@@ -240,6 +245,11 @@ interface OpenSpecIntegrationMeta {
         requiresOpenspec: string;
         files: Record<string, string>;
     };
+    recoverySchema?: {
+        name: string;
+        requiresOpenspec: string;
+        files: Record<string, string>;
+    };
 }
 /** The repository-relative path of the integration metadata file, for callers that probe it. */
 declare const OPENSPEC_META_RELATIVE = ".product/integrations/openspec.json";
@@ -402,4 +412,4 @@ declare function removeOpenSpecIntegration(root: string, options?: {
     preserved: string[];
 }>;
 
-export { type DeliveryContextBundle, type DeliveryContextEntry, MIN_SUPPORTED_OPENSPEC, type ManagedStrings, OPENSPEC_CI_EXAMPLE_RELATIVE, OPENSPEC_META_RELATIVE, OPENSPEC_NPX_SPEC, OPENSPEC_PRODUCT_SCHEMA_NAME, OPENSPEC_PRODUCT_SCHEMA_RELATIVE, OPENSPEC_PRODUCT_SUBDIR, OPENSPEC_VERIFY_COMMAND, type OpenSpecIntegrationMeta, OpenSpecMetaError, type OpenSpecProductApplyOutcome, type OpenSpecProductApplyResult, type OpenSpecProductChangeRef, type OpenSpecProductChangeValidation, PDAC_CONTEXT_BLOCK, PDAC_OPERATIONS, PDAC_RULES, PRODUCT_SCHEMA_MIN_OPENSPEC, type ProductModelInspection, type ProductSchemaAsset, addOpenSpecIntegration, applyOpenSpecProductChange, bootstrapOpenSpecWorkspace, checkOpenSpecIntegration, currentManagedStrings, deriveDeliveryContext, detectOpenSpecVersion, enumerateOpenSpecDocuments, inspectProductModel, isOpenSpecCliAvailable, isOpenSpecIntegrationInstalled, isOpenSpecWorkspace, listOpenSpecProductChanges, loadOpenSpecProductChange, loadProductSchemaAssets, mergeConfig, openSpecProvider, readOpenSpecConfig, removeOpenSpecIntegration, renderCiExample, serializeConfig, updateOpenSpecIntegration, validateOpenSpecProductChange };
+export { type DeliveryContextBundle, type DeliveryContextEntry, MIN_SUPPORTED_OPENSPEC, type ManagedStrings, OPENSPEC_CI_EXAMPLE_RELATIVE, OPENSPEC_META_RELATIVE, OPENSPEC_NPX_SPEC, 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, type OpenSpecIntegrationMeta, OpenSpecMetaError, type OpenSpecProductApplyOutcome, type OpenSpecProductApplyResult, type OpenSpecProductChangeRef, type OpenSpecProductChangeValidation, PDAC_CONTEXT_BLOCK, PDAC_OPERATIONS, PDAC_RULES, PRODUCT_CHANGE_SCHEMA_MIN_OPENSPEC, type ProductChangeSchemaAsset, type ProductModelInspection, addOpenSpecIntegration, applyOpenSpecProductChange, bootstrapOpenSpecWorkspace, checkOpenSpecIntegration, currentManagedStrings, deriveDeliveryContext, detectOpenSpecVersion, enumerateOpenSpecDocuments, inspectProductModel, isOpenSpecCliAvailable, isOpenSpecIntegrationInstalled, isOpenSpecWorkspace, listOpenSpecProductChanges, loadOpenSpecProductChange, loadProductChangeSchemaAssets, loadProductRecoverySchemaAssets, mergeConfig, openSpecProvider, readOpenSpecConfig, removeOpenSpecIntegration, renderCiExample, serializeConfig, updateOpenSpecIntegration, validateOpenSpecProductChange };