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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { EnumerateConsumerDocumentsOptions, ConsumerDocumentEnumeration, SddIntegrationProvider } from '@prodshape/core';
+import { EnumerateConsumerDocumentsOptions, ConsumerDocumentEnumeration, SddIntegrationProvider, ImpactReport, ApplyPlan, LoadedChange, BaselineValidation, LoadedArtifact, ProductGraph, Diagnostic, ProductRepository } from '@prodshape/core';
 
 /** Check if an OpenSpec workspace exists at the given root (openspec/ directory present). */
 declare function isOpenSpecWorkspace(root: string): Promise<boolean>;
@@ -31,6 +31,144 @@ 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";
+/** The repository-relative directory the product schema is installed into. */
+declare const OPENSPEC_PRODUCT_SCHEMA_RELATIVE = "openspec/schemas/product";
+/**
+ * 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
+ * `skip_specs: true` for schemas with no specs artifact (so `openspec validate` stops demanding
+ * delta specs), artifacts follow schema declaration order, and the generated skills stop
+ * overriding custom-schema instructions with spec-driven patterns. Below this floor the schema
+ * 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";
+/** One bundled product-schema file: its path relative to the installed schema directory. */
+interface ProductSchemaAsset {
+    relative: string;
+    content: string;
+}
+/**
+ * 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[]>;
+
+/** The subdirectory of an OpenSpec change that hosts the PDaC Product Change delta. */
+declare const OPENSPEC_PRODUCT_SUBDIR = "product";
+/** The accepted product model, read directly from disk and validated, with its in-memory graph. */
+interface ProductModelInspection {
+    repo: ProductRepository;
+    artifacts: LoadedArtifact[];
+    graph: ProductGraph;
+    /** Configuration diagnostics plus full baseline validation, sorted. */
+    diagnostics: Diagnostic[];
+}
+/**
+ * Read the accepted model at the repository's product root (default docs/product), compile the
+ * semantic graph in memory and validate. Needs no `.product/generated` output and no
+ * configuration file: kernel defaults apply when `.product/config.yaml` is absent.
+ */
+declare function inspectProductModel(root: string): Promise<ProductModelInspection>;
+/** One OpenSpec change hosting a PDaC Product Change delta. */
+interface OpenSpecProductChangeRef {
+    /** The OpenSpec change name (the directory under openspec/changes/). */
+    name: string;
+    /** Absolute path of the hosted PDaC change directory (…/<name>/product). */
+    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
+ * 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
+ * concurrency input.
+ */
+declare function listOpenSpecProductChanges(root: string): Promise<OpenSpecProductChangeRef[]>;
+/** Load one hosted Product Change through core's loader (change.md plus proposed/**). */
+declare function loadOpenSpecProductChange(root: string, changeName: string): Promise<LoadedChange>;
+/** The result of validating a hosted Product Change as an overlay on the untouched baseline. */
+interface OpenSpecProductChangeValidation {
+    change: LoadedChange;
+    baseline: BaselineValidation;
+    overlayArtifacts: LoadedArtifact[];
+    overlayGraph: ProductGraph;
+    /** Configuration, baseline and change diagnostics, deduplicated and sorted. */
+    diagnostics: Diagnostic[];
+    /** The diagnostics that block, under the repository's warnings-as-errors policy. */
+    blocking: Diagnostic[];
+}
+/**
+ * Validate one hosted Product Change: the accepted baseline stays untouched, the delta is
+ * compiled over it into an overlay, and the overlay is validated end to end (operation checks,
+ * cross-container concurrency, open-questions state, full structural validation with the
+ * PRODUCT023/PRODUCT024 overlay recodes). Useful as explicit preflight and for wrappers and
+ * tests; apply never trusts it and revalidates on its own.
+ */
+declare function validateOpenSpecProductChange(root: string, changeName: string): Promise<OpenSpecProductChangeValidation>;
+/** How an apply invocation ended. */
+type OpenSpecProductApplyOutcome = 'applied' | 'dry-run' | 'refused';
+interface OpenSpecProductApplyResult {
+    outcome: OpenSpecProductApplyOutcome;
+    /**
+     * The executed (or refused) plan. The ProductShape lifecycle's `move-change` action is already
+     * filtered out: the hosted change directory belongs to OpenSpec and only `openspec archive`
+     * moves it, as a separate action after apply.
+     */
+    plan: ApplyPlan;
+    change: LoadedChange;
+    /** Fresh read and validation of the accepted model after a real apply. */
+    resultingModel?: BaselineValidation;
+}
+/**
+ * Apply one hosted Product Change to the accepted model, deterministically and fail closed.
+ *
+ * The sequence mirrors the native apply and is fail closed end to end: full revalidation at apply
+ * time of the configuration, the baseline (including its per-document load diagnostics) and the
+ * overlay, the apply-authorised state gate (PRODUCT028; the integration never performs the
+ * authorising transition), base-revision drift by content digest (PRODUCT027), write and delete
+ * actions named by lowercase id, the product diff computed from the result, and the hosted
+ * change.md status flipped to applied in place. Any blocking diagnostic refuses BEFORE any
+ * mutation, with `docs/product/model` and the change container byte-identical. A dry run still
+ * preflights every action. Nothing is committed and nothing is archived: verification and the
+ * container move remain separate, later actions.
+ */
+declare function applyOpenSpecProductChange(root: string, changeName: string, options?: {
+    dryRun?: boolean;
+}): Promise<OpenSpecProductApplyResult>;
+/** One artifact carried into delivery context, with the digest of its current accepted content. */
+interface DeliveryContextEntry {
+    id: string;
+    type?: string;
+    title?: string;
+    status?: string;
+    file: string;
+    digest: string;
+}
+/** Context derived from a fresh read of the accepted model, for a later delivery workflow. */
+interface DeliveryContextBundle {
+    ids: string[];
+    /** The requested artifacts, from the freshly read accepted model. */
+    artifacts: DeliveryContextEntry[];
+    /** Impact around each requested artifact (direction both, depth 2). */
+    impacts: Record<string, ImpactReport>;
+    /** Direct neighbours of the requested artifacts, deduplicated, requested ids excluded. */
+    neighbours: DeliveryContextEntry[];
+    /** Whether the freshly read accepted model validates with zero errors. */
+    modelErrorFree: boolean;
+}
+/**
+ * Derive delivery context from the accepted model as it exists on disk NOW: a fresh read and a
+ * fresh graph, never state carried over from a product workflow. This is the handoff boundary a
+ * future delivery workflow starts from.
+ */
+declare function deriveDeliveryContext(root: string, ids: string[]): Promise<DeliveryContextBundle>;
+
 /** The minimum supported OpenSpec CLI version. */
 declare const MIN_SUPPORTED_OPENSPEC = "1.0.0";
 /**
@@ -40,7 +178,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 under docs/product/changes/: validate it as an overlay while the baseline stays untouched, obtain human product approval, 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. OpenSpec changes never edit docs/product/model directly: an OpenSpec change 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.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 -->";
 /** 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:`. */
@@ -86,6 +224,22 @@ interface OpenSpecIntegrationMeta {
     ciExamplePath?: string;
     /** Absent in metadata written before the field existed; treated as the current guidance. */
     managed?: ManagedStrings;
+    /**
+     * The installed OpenSpec product schema: its name, the OpenSpec floor the product workflow
+     * needs, and every managed file it consists of, each with the content digest it was installed
+     * at. The per-file record and digest are the ownership proof (ADR 0008): update replaces and
+     * remove deletes a file only when that exact path was recorded and its bytes still match the
+     * recorded digest (legacy path-only records additionally require the current asset bytes). A
+     * diverged or unrecorded file is preserved and reported, never overwritten or deleted. Absent in metadata written before the
+     * schema existed; `integration update` installs the schema and adds the record. Metadata
+     * written by earlier spike revisions carried a plain path array; it is read as paths with no
+     * recorded digest, so ownership then rests on matching the current assets.
+     */
+    productSchema?: {
+        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";
@@ -216,6 +370,9 @@ declare function updateOpenSpecIntegration(root: string, options?: {
  * - `openspec/config.yaml` exists and contains the PDaC context block.
  * - `.product/integrations/openspec.json` metadata exists.
  * - The config's PDaC block matches the current PDaC guidance (not removed or altered).
+ * - The product schema's managed files are installed and intact, with the product workflow's
+ *   availability reported per capability: an OpenSpec CLI below the product floor leaves the
+ *   citation lane usable and states the product workflow UNAVAILABLE instead of failing it.
  */
 declare function checkOpenSpecIntegration(root: string): Promise<{
     ok: boolean;
@@ -232,13 +389,17 @@ declare function checkOpenSpecIntegration(root: string): Promise<{
  * - Removes the PDaC context block (between sentinels) from `context:`.
  * - Removes PDaC rules from each artifact (keeps user-authored rules).
  * - Removes PDaC operation guidance (keeps user-authored guidance).
+ * - Deletes the installed product schema files still proven managed (recorded digest or current
+ *   asset bytes); hand-edited managed files are preserved and reported in `preserved`, and with
+ *   no recorded product schema nothing under openspec/schemas is touched.
  * - Deletes `.product/integrations/openspec.json`.
- * - `--dry-run` reports what would be removed without writing.
+ * - `--dry-run` reports what would be removed and preserved without writing.
  */
 declare function removeOpenSpecIntegration(root: string, options?: {
     dryRun?: boolean;
 }): Promise<{
     removed: string[];
+    preserved: string[];
 }>;
 
-export { MIN_SUPPORTED_OPENSPEC, type ManagedStrings, OPENSPEC_CI_EXAMPLE_RELATIVE, OPENSPEC_META_RELATIVE, OPENSPEC_NPX_SPEC, OPENSPEC_VERIFY_COMMAND, type OpenSpecIntegrationMeta, OpenSpecMetaError, PDAC_CONTEXT_BLOCK, PDAC_OPERATIONS, PDAC_RULES, addOpenSpecIntegration, bootstrapOpenSpecWorkspace, checkOpenSpecIntegration, currentManagedStrings, detectOpenSpecVersion, enumerateOpenSpecDocuments, isOpenSpecCliAvailable, isOpenSpecIntegrationInstalled, isOpenSpecWorkspace, mergeConfig, openSpecProvider, readOpenSpecConfig, removeOpenSpecIntegration, renderCiExample, serializeConfig, updateOpenSpecIntegration };
+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 };