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

package/README.md

@@ -0,0 +1,64 @@
+# @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/`) 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.
+
+## 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` 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 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.
+
+The primary workflow is OpenSpec's own:
+
+```text
+/opsx:new <change> --schema product
+        |
+/opsx:continue (or /opsx:ff)      authors proposal.md, then product/change.md + product/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/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.
+
+### 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.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.

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

@@ -0,0 +1,120 @@
+# 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
+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.
+
+      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.
+    requires: []
+
+  - id: delta
+    generates: 'product/**/*.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
+      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:
+      - 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.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
+        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.
+      - 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/scripts/product-validate.mjs --change <change-name>` validates the
+      accepted baseline plus this delta as an overlay without touching either.
+    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.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.
+    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`
+       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-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/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>]',
+  );
+  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-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/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>]',
+  );
+  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-schema/templates/change.md

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

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

@@ -0,0 +1,29 @@
+<!-- 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.
+
+## 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.