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

package/README.md

@@ -0,0 +1,68 @@
+# @prodshape/integration-openspec
+
+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-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)
+
+The integration merges PDaC authority context and citation rules into `openspec/config.yaml` and installs a CI-ready verification example. Spec-driven OpenSpec documents cite canonical product artifacts by id and sha256 digest; `prodshape citations verify --provider openspec` resolves every citation against the model and enforces the scope-declaration population contract. A spec-driven delivery change never edits `docs/product/model`.
+
+## The product lane (the hosted product workflow)
+
+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.
+
+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-change
+        |
+/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
+        |
+/opsx:archive <change>            a separate action after successful apply and verification
+```
+
+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-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/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
+
+- OpenSpec >= 1.7.0 for the product workflow (`skip_specs` change metadata, declaration-order artifacts, schema-agnostic skill instructions). The schema files install under any supported OpenSpec (>= 1.0.0) and are inert data below the floor: `prodshape doctor` then reports the product workflow UNAVAILABLE while the citation lane keeps working.
+- `@prodshape/integration-openspec` installed locally (`npm install --save-dev @prodshape/integration-openspec`). The ProductShape CLI bundles this package for its own commands, so a CLI-only installation does not put it in `node_modules`; the bridge scripts need the package resolvable from the repository and say so when it is not. This documented installation is proven end to end by the packed-consumer suite, which installs the packed tarballs into a fresh repository and runs the bridge scripts by bare specifier with no override.
+- `@prodshape/cli` available locally for the authoring capabilities the schema instructions name (`prodshape inspect`, `prodshape impact`, `prodshape template <kind>`, `prodshape validate`).
+
+## Library API
+
+The deterministic rails are exported for wrappers, tests and custom callers; the bridge scripts are thin argument parsers over them.
+
+```ts
+import {
+  inspectProductModel, // accepted model + in-memory graph + diagnostics
+  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
+  deriveDeliveryContext, // fresh post-apply context for a future delivery workflow
+} from '@prodshape/integration-openspec';
+```
+
+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-change-schema/schema.yaml

@@ -0,0 +1,151 @@
+# 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-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.
+artifacts:
+  - id: intent
+    generates: proposal.md
+    description: Requested product intent, grounded in the accepted product model
+    template: proposal.md
+    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.
+      2. Compare the request with the whole definition, then widen through the product graph:
+         for every artifact the request depends on, alters or contradicts, inspect its neighbours and impact.
+         The repository's ProductShape tooling provides this deterministically: `prodshape inspect <ID>` and
+         `prodshape impact <ID>` resolve the locally installed @prodshape/cli. Install the CLI locally
+         (a devDependency counts) rather than relying on network resolution.
+      3. List every impacted artifact in the proposal and name any neighbour you checked and left out.
+      4. Cite the artifacts the intent stands on: read the digest with `prodshape inspect <ID>`, emit the
+         payload with `prodshape cite --id <ID> --digest <digest>`, and wrap it in an HTML comment on its
+         own line. Declare the document scope: `pdac-scope: cited` when the proposal carries citations, or
+         `pdac-scope: none` with a non-empty human reason when no product text is involved.
+
+      Before declaring the intent ready, actively look for wording that permits materially different
+      product outcomes. Compare those alternatives in product-observable terms. When the accepted model
+      and the request do not select one outcome, put the alternatives under "Open Questions for the
+      Product Owner", ask the user for the missing decision, and STOP before authoring the delta. Never
+      silently select, combine or narrow product meaning on the user's behalf. `None.` is appropriate only
+      after this ambiguity pass finds no unresolved decision that would change product behaviour, scope,
+      policy or acceptance.
+
+      Decide the outcome honestly. When the request changes no product meaning (tooling, refactoring,
+      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-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/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
+        intended outcome; do not merely delete the question.
+      - change.md frontmatter carries id (CHG-...), type: product-change, title, status: draft,
+        base-revision (the commit the change was authored against, `git rev-parse --short HEAD`, quoted),
+        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/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-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
+        locally installed @prodshape/cli.
+      - Keep typed relationships resolvable: primary-actor, steps[].use-case, bounded-context,
+        governed-by, uses-terms, applies-to, defined-in, derived-from, illustrates and
+        verification[].scenario-ref must point at ids that exist in the baseline or in this delta.
+      - Stay in product semantics: no file paths, package names or implementation detail inside product
+        artifacts. Add a structured-behaviour only where it clarifies observable product behaviour
+        (given/when/then in frontmatter, Intent and Boundaries body sections).
+      - Leave status: draft while authoring. Status approved records human product approval under
+        ProductShape's accepted policy; that decision happens outside this artifact, and neither
+        this workflow nor the integration grants it.
+      - Never edit docs/product/model directly; the accepted model changes only through the
+        deterministic apply of this change.
+
+      Preflight is available at any time:
+      `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
+
+apply:
+  requires:
+    - delta
+  instruction: |
+    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/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-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
+       docs/product/model untouched, enforces base-revision drift (PRODUCT027) and the
+       apply-authorised state (PRODUCT028), writes the delta into the model, reports the product diff
+       computed from the result and flips this change's status to applied in place.
+    3. Re-read docs/product/model and validate the resulting accepted model: `prodshape validate` must
+       report zero errors. Refresh any citations the reported diff made stale.
+    4. STOP. Do not archive this change as part of apply: archiving is a separate OpenSpec action
+       performed after successful Product apply and verification. Do not implement delivery work, do
+       not modify implementation code and never edit docs/product/model by hand.

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

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// MANAGED FILE. Installed by `prodshape integration add openspec` as part of the OpenSpec product
+// schema. The executable bridge from the schema's apply instruction to the deterministic apply
+// rail: the apply logic lives in @prodshape/integration-openspec (applyOpenSpecProductChange);
+// this script only resolves the local installation, invokes it and reports. It revalidates the
+// overlay at apply time, refuses with the model untouched on any blocking diagnostic, requires
+// the apply-authorised state (status: approved) and never archives the change.
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import process from 'node:process';
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+// 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-change/scripts/product-apply.mjs --change <name> [--dry-run] [--root <dir>]',
+  );
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const args = { change: undefined, root: undefined, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--change') {
+      args.change = argv[(i += 1)];
+    } else if (arg === '--root') {
+      args.root = argv[(i += 1)];
+    } else if (arg === '--dry-run') {
+      args.dryRun = true;
+    } else {
+      usage(`Unknown argument: ${arg}`);
+    }
+  }
+  if (!args.change) usage('Missing --change <name>.');
+  return args;
+}
+
+async function loadIntegration() {
+  const override = process.env.PRODSHAPE_INTEGRATION_OPENSPEC_ENTRY;
+  if (override) {
+    const url = override.startsWith('file:') ? override : pathToFileURL(resolve(override)).href;
+    return import(url);
+  }
+  try {
+    return await import('@prodshape/integration-openspec');
+  } catch (error) {
+    console.error('Could not resolve @prodshape/integration-openspec from this repository.');
+    console.error('The product workflow bridge needs the integration package installed locally:');
+    console.error('  npm install --save-dev @prodshape/integration-openspec');
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(2);
+  }
+}
+
+function printDiagnostics(diagnostics) {
+  for (const diagnostic of diagnostics) {
+    const attrs = ['artifact', 'change', 'field', 'target', 'line', 'entry']
+      .filter((key) => diagnostic[key] !== undefined)
+      .map((key) => `${key}=${diagnostic[key]}`)
+      .join(' ');
+    console.log(
+      `${diagnostic.severity} ${diagnostic.code} ${diagnostic.file}${attrs ? ` ${attrs}` : ''}: ${diagnostic.message}`,
+    );
+  }
+}
+
+const args = parseArgs(process.argv.slice(2));
+const repoRoot = args.root ? resolve(args.root) : defaultRoot;
+const integration = await loadIntegration();
+const result = await integration.applyOpenSpecProductChange(repoRoot, args.change, {
+  dryRun: args.dryRun,
+});
+printDiagnostics(result.plan.diagnostics);
+if (result.outcome === 'refused') {
+  console.log('Apply refused; docs/product/model untouched.');
+  process.exit(1);
+}
+for (const action of result.plan.actions) {
+  console.log(`${action.kind}: ${action.description}`);
+}
+const { added, modified, removed } = result.plan.diff;
+console.log(
+  `Product diff: ${added.length} added, ${modified.length} modified, ${removed.length} removed.`,
+);
+if (result.outcome === 'dry-run') {
+  console.log('Dry run; nothing was written.');
+  process.exit(0);
+}
+const resultingErrors = (result.resultingModel?.diagnostics ?? []).filter(
+  (diagnostic) => diagnostic.severity === 'error',
+);
+if (resultingErrors.length > 0) {
+  printDiagnostics(resultingErrors);
+  console.log(
+    'Applied, but the resulting accepted model reports errors. Investigate before archiving.',
+  );
+  process.exit(1);
+}
+console.log(
+  'Applied. Nothing was committed and the change was not archived: verify the model, then archive separately.',
+);

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

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// MANAGED FILE. Installed by `prodshape integration add openspec` as part of the OpenSpec product
+// schema. Deterministic overlay preflight for a hosted Product Change: the validation logic lives
+// in @prodshape/integration-openspec; this script only resolves the local installation, invokes it
+// and reports. It writes nothing.
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import process from 'node:process';
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+// 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-change/scripts/product-validate.mjs --change <name> [--root <dir>]',
+  );
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const args = { change: undefined, root: undefined };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--change') {
+      args.change = argv[(i += 1)];
+    } else if (arg === '--root') {
+      args.root = argv[(i += 1)];
+    } else {
+      usage(`Unknown argument: ${arg}`);
+    }
+  }
+  if (!args.change) usage('Missing --change <name>.');
+  return args;
+}
+
+async function loadIntegration() {
+  const override = process.env.PRODSHAPE_INTEGRATION_OPENSPEC_ENTRY;
+  if (override) {
+    const url = override.startsWith('file:') ? override : pathToFileURL(resolve(override)).href;
+    return import(url);
+  }
+  try {
+    return await import('@prodshape/integration-openspec');
+  } catch (error) {
+    console.error('Could not resolve @prodshape/integration-openspec from this repository.');
+    console.error('The product workflow bridge needs the integration package installed locally:');
+    console.error('  npm install --save-dev @prodshape/integration-openspec');
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(2);
+  }
+}
+
+function printDiagnostics(diagnostics) {
+  for (const diagnostic of diagnostics) {
+    const attrs = ['artifact', 'change', 'field', 'target', 'line', 'entry']
+      .filter((key) => diagnostic[key] !== undefined)
+      .map((key) => `${key}=${diagnostic[key]}`)
+      .join(' ');
+    console.log(
+      `${diagnostic.severity} ${diagnostic.code} ${diagnostic.file}${attrs ? ` ${attrs}` : ''}: ${diagnostic.message}`,
+    );
+  }
+}
+
+const args = parseArgs(process.argv.slice(2));
+const repoRoot = args.root ? resolve(args.root) : defaultRoot;
+const integration = await loadIntegration();
+const result = await integration.validateOpenSpecProductChange(repoRoot, args.change);
+printDiagnostics(result.diagnostics);
+if (result.blocking.length > 0) {
+  const count = result.blocking.length;
+  console.log(`Overlay validation: FAIL (${count} blocking diagnostic${count === 1 ? '' : 's'}).`);
+  process.exit(1);
+}
+console.log('Overlay validation: PASS.');

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-change-schema/templates/proposal.md

@@ -0,0 +1,41 @@
+<!-- pdac-scope: cited -->
+
+# <Requested product change title>
+
+Declare the document scope on the first line: keep `pdac-scope: cited` when this proposal carries citations (the normal case), or replace it with `<!-- pdac-scope: none reason="<why no product text is involved>" -->`.
+
+## Why
+
+The request as it arrived: the Issue, ask or observation that started this change, in one or two sentences.
+
+## Requested Product Intent
+
+What the product should mean once this change is accepted, in product language. Destination, not steps; no implementation detail.
+
+## Impacted Product Areas
+
+Every accepted artifact this intent depends on, alters or contradicts. One line per artifact: the id, why it is impacted, and a citation payload on its own line directly under it (emit with `prodshape cite --id <ID> --digest <digest>`, never write one by hand).
+
+## Neighbours Checked and Left Out
+
+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.
+
+## Open Questions for the Product Owner
+
+Questions that must be answered before the delta can be authored or authorised. First identify any wording that permits materially different observable product outcomes and list the alternatives here. Ask the product owner and stop before the delta until each such decision is answered. Never choose an outcome on the user's behalf. Write `None.` only after this ambiguity pass finds no unresolved decision that would change product behaviour, scope, policy or acceptance.

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.