@prodshape/integration-openspec 0.1.0 → 0.4.0

package/src/index.ts

@@ -13,13 +13,28 @@
  * guidance, deduplicating identical entries so the operation is idempotent.
  */
 import { execFile } from 'node:child_process';
-import { access, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { parse, stringify } from 'yaml';
+import { envWithLocalBin, isOpenSpecWorkspace, pathExists } from './workspace.js';
+
+export { isOpenSpecWorkspace } from './workspace.js';
+export {
+  enumerateOpenSpecDocuments,
+  isOpenSpecCliAvailable,
+  openSpecProvider,
+} from './population.js';
 
 /** The minimum supported OpenSpec CLI version. */
 export const MIN_SUPPORTED_OPENSPEC = '1.0.0';
 
+/**
+ * The npm spec used when bootstrapping OpenSpec through npx. Pinned to the supported major:
+ * MIN_SUPPORTED_OPENSPEC guards the floor, the pin guards the ceiling, so a future OpenSpec 2.x
+ * cannot silently change what `init --tools none` does for new adopters.
+ */
+export const OPENSPEC_NPX_SPEC = '@fission-ai/openspec@1';
+
 /**
  * Sentinel markers that bracket the PDaC-injected context block. They let `mergeConfig` find
  * and replace exactly the PDaC portion without touching user-authored context lines.
@@ -32,14 +47,19 @@ export const PDAC_CONTEXT_BLOCK = `${PDAC_CONTEXT_BEGIN}
 This repository uses Product Definition as Code (PDaC). The canonical product definition lives in docs/product/model (actors, journeys, use cases, business rules, domain terms, requirements) and is the single source of truth for product behaviour. OpenSpec artifacts are downstream consumers of it, never a second source of truth.
 Consumers bind to canonical text through the PDaC Citation Contract: a citation records the target artifact id, a sha256 content digest, and an optional verification scenario anchor. Verification reports one status per citation: current, stale, tampered or unresolved.
 To cite: run \`npx prodshape inspect <ID>\` to read the current digest, then \`npx prodshape cite --id <ID> --digest <digest>\` to emit the citation record. Place inline citations on their own line directly under the text they ground.
-The product definition changes only through a Product Change under docs/product/changes/. OpenSpec changes never edit docs/product/model directly.
+Finding which artifacts a change impacts is understanding work: 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 — never fix it quietly.
+Every current OpenSpec document (proposal, specs, design, tasks and openspec/specs/) has exactly one effective scope state: bound (it carries at least one citation, or declares \`pdac-scope: cited\`), exempt (a human declared \`pdac-scope: none\` because the document has no product-semantic dependency), or unclassified (neither declared — a verification failure). Binding and exemption are human declarations: never declare \`pdac-scope: none\` merely because citations are missing, and a document declared \`pdac-scope: cited\` with zero citations fails. Verify with \`npx prodshape citations verify --provider openspec\`: it enumerates the expected document population, so zero discovered citations is a set of failures, never a pass. The scope gate applies to current documents; citations in archived changes are still checked, but their problems are reported as warnings, because archived history cannot be edited and its drift is information for the reader.
+The accepted Product Definition changes only through this lifecycle: propose a Product Change under docs/product/changes/, validate its overlay while the baseline remains untouched, obtain human product approval, apply explicitly on a working branch, review the applied result in a pull request, and accept the resulting baseline by human merge. A Product Change is not a pull request. Apply is not acceptance, and neither apply nor merge attests implementation, verification, release or deployment. OpenSpec changes never edit docs/product/model directly. Product-definition work and implementation work have independent cadence: an OpenSpec change may share a pull request with an applied Product Change or follow an accepted definition later, but it remains a downstream implementation concern and never supplies Product Change status.
 ${PDAC_CONTEXT_END}`;
 
 /** The PDaC citation rules injected per artifact into openspec/config.yaml `rules:`. */
 export const PDAC_RULES: Record<string, string[]> = {
   proposal: [
     'State which PDaC artifacts this change touches, each with an inline citation emitted by `npx prodshape cite --id <ID> --digest <digest>`. Never write a citation record by hand.',
-    'If the change alters product behaviour, name the Product Change (CHG id) it implements. If no Product Change exists yet, stop and ask for one instead of proceeding.',
+    'Find the impacted artifacts as a separate step before writing any proposal content. This is understanding work, not lookup: read the whole product definition (docs/product/model by default), compare it with what this change wants — the backlog item behind it, if there is one — and list every artifact the change depends on, alters or contradicts. Then widen the list with the graph: run `npx prodshape impact <ID>` on each artifact you found and check its direct and indirect neighbours. Put the resulting list in the proposal, cite every impacted artifact from each document that uses it (proposal, specs, design, tasks), and name any neighbour you checked and left out, so nothing is dropped silently.',
+    'If this change\'s goals contradict the product definition, or need behaviour it does not describe, that is product-definition drift. Record it in the proposal under a \'Product definition drift\' note naming the artifacts involved, with the marker `<!-- pdac-drift ids="<ID>[, <ID>...]" summary="<one line>" -->` on its own line so `npx prodshape drift` can list it. The decision is human: the developer and the product owner agree whether to propose a Product Change or adjust this change. Never fix drift quietly, drop or weaken a citation to hide it, or write around the conflict.',
+    'If the change implements altered product behaviour, name the Product Change (CHG id) whose applied or accepted artifacts it implements. If no overlay-validated and human-approved Product Change exists yet, stop and ask for one instead of proceeding. The OpenSpec change is not the Product Change.',
+    'Every document of this change must end up bound or exempt: bind by citing the canonical text it depends on, or declare `pdac-scope: none` on a line of its own (frontmatter or `<!-- pdac-scope: none -->`) when a human judges the document has no product-semantic dependency. Never declare an exemption just because citations are missing.',
   ],
   specs: [
     'Every requirement derived from canonical product text MUST carry a citation to every PDaC artifact it derives from, one citation per line, placed after the requirement text and before the first scenario. A requirement often derives from more than one artifact; citing only the closest one silently hides the other derivations. Never place citations between the requirement heading and the requirement text; OpenSpec reads the first paragraph as the requirement.',
@@ -52,6 +72,7 @@ export const PDAC_RULES: Record<string, string[]> = {
   ],
   tasks: [
     'A task that changes cited behaviour must include a follow-up task to refresh the affected citations.',
+    'Never infer implementation, verification, release or deployment from Product Change status; record that evidence in the delivery workflow.',
   ],
 };
 
@@ -62,16 +83,36 @@ export const PDAC_OPERATIONS: {
 } = {
   apply: {
     guidance: [
-      'Before finishing, run `npx prodshape citations verify` and fix every stale, tampered or unresolved citation. Refresh a stale digest by re-running `npx prodshape inspect <ID>`; never delete a citation to silence a diagnostic.',
+      'Before finishing, run `npx prodshape citations verify --provider openspec` and fix every stale, tampered or unresolved citation, every unclassified document and every bound document without citations. Refresh a stale digest by re-running `npx prodshape inspect <ID>`; never delete a citation or declare `pdac-scope: none` to silence a diagnostic.',
     ],
   },
   archive: {
     guidance: [
-      'Run `npx prodshape citations verify` one final time. Archive only when every citation is current.',
+      'Run `npx prodshape citations verify --provider openspec` one final time. Archive only when every document is bound or exempt and every citation is current.',
     ],
   },
 };
 
+/**
+ * The exact strings PDaC injected into openspec/config.yaml, recorded so a later update can
+ * remove entries whose wording has since changed instead of appending duplicates alongside them.
+ * The context block needs no record: its sentinels already identify it in place.
+ */
+export interface ManagedStrings {
+  rules: Record<string, string[]>;
+  operations: Record<string, string[]>;
+}
+
+/** The managed strings the current PDaC guidance injects. */
+export function currentManagedStrings(): ManagedStrings {
+  return {
+    rules: Object.fromEntries(Object.entries(PDAC_RULES).map(([key, list]) => [key, [...list]])),
+    operations: Object.fromEntries(
+      Object.entries(PDAC_OPERATIONS).map(([key, op]) => [key, [...op.guidance]]),
+    ),
+  };
+}
+
 /** Metadata recorded under .product/integrations/openspec.json. */
 export interface OpenSpecIntegrationMeta {
   provider: 'openspec';
@@ -79,11 +120,84 @@ export interface OpenSpecIntegrationMeta {
   openspecVersion: string;
   installedAt: string;
   configPath: string;
+  /** Absent in metadata written before the CI example existed; `integration update` adds it. */
+  ciExamplePath?: string;
+  /** Absent in metadata written before the field existed; treated as the current guidance. */
+  managed?: ManagedStrings;
 }
 
 /** Repository-relative paths used by this integration. */
 const CONFIG_RELATIVE = 'openspec/config.yaml';
 const META_RELATIVE = '.product/integrations/openspec.json';
+const CI_EXAMPLE_RELATIVE = '.product/integrations/openspec.ci.yml';
+
+/** The repository-relative path of the integration metadata file, for callers that probe it. */
+export const OPENSPEC_META_RELATIVE = META_RELATIVE;
+
+/** The repository-relative path of the installed CI-ready example workflow. */
+export const OPENSPEC_CI_EXAMPLE_RELATIVE = CI_EXAMPLE_RELATIVE;
+
+/** The exact provider-aware verification command the integration stands behind. */
+export const OPENSPEC_VERIFY_COMMAND = 'npx prodshape citations verify --provider openspec';
+
+/**
+ * Render the CI-ready example workflow installed at {@link OPENSPEC_CI_EXAMPLE_RELATIVE}.
+ *
+ * The gate always blocks unresolved citations, tampered embedded projections, unclassified
+ * current documents and bound documents with zero citations. Stale citations follow the
+ * repository's configured warning policy (`validation.warnings-as-errors` in
+ * `.product/config.yaml`); the example never changes that policy, but it states explicitly what
+ * the repository's current choice means and how to escalate it, so the blocking behaviour is a
+ * deliberate decision rather than a silent default.
+ */
+export function renderCiExample(options: { warningsAsErrors: boolean }): string {
+  const stalePolicy = options.warningsAsErrors
+    ? [
+        '# - stale citations BLOCK this gate: .product/config.yaml sets',
+        '#   `validation.warnings-as-errors: true`, escalating the PRODUCT061 warning to an error.',
+        '#   The integration never changes that policy; relax it by setting the key to false.',
+      ]
+    : [
+        '# - stale citations DO NOT block this gate: .product/config.yaml sets',
+        '#   `validation.warnings-as-errors: false`, so PRODUCT061 stays a warning. To make stale',
+        '#   citations block the merge, set `validation.warnings-as-errors: true` in',
+        '#   .product/config.yaml. The integration never changes that policy for you.',
+      ];
+  return [
+    '# PDaC citation gate for OpenSpec consumer documents (CI-ready example).',
+    '# Managed by `prodshape integration add openspec`; copy it into your pipeline',
+    '# (e.g. .github/workflows/) and adapt the triggers.',
+    '#',
+    '# The gate runs ProductShape citation and scope verification only. It never invokes',
+    "# `openspec validate`; keep OpenSpec's own verdict a separate step so a native-spec defect",
+    '# and a grounding defect stay distinguishable.',
+    '#',
+    '# Blocking behaviour:',
+    '# - unresolved citations, tampered embedded projections, unclassified current documents',
+    '#   and bound documents with zero citations always fail the gate;',
+    ...stalePolicy,
+    '# - citations in archived changes are checked too, but their problems are reported as',
+    '#   warnings: archived history cannot be edited, so a problem there is information,',
+    '#   not something this gate can make anyone fix. Pass --include-archived to apply the',
+    '#   full gate to archived documents as well.',
+    'name: pdac-citations',
+    'on:',
+    '  pull_request:',
+    'jobs:',
+    '  verify:',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    '      - uses: actions/checkout@v4',
+    '      - uses: actions/setup-node@v4',
+    '        with:',
+    "          node-version: '22'",
+    '      # The OpenSpec CLI ships as @fission-ai/openspec; population discovery runs',
+    '      # `openspec list`, so the gate needs it installed.',
+    `      - run: npm install -g ${OPENSPEC_NPX_SPEC}`,
+    `      - run: ${OPENSPEC_VERIFY_COMMAND}`,
+    '',
+  ].join('\n');
+}
 
 function configPath(root: string): string {
   return join(root, ...CONFIG_RELATIVE.split('/'));
@@ -93,13 +207,8 @@ function metaPath(root: string): string {
   return join(root, ...META_RELATIVE.split('/'));
 }
 
-async function exists(path: string): Promise<boolean> {
-  try {
-    await access(path);
-    return true;
-  } catch {
-    return false;
-  }
+function ciExamplePath(root: string): string {
+  return join(root, ...CI_EXAMPLE_RELATIVE.split('/'));
 }
 
 /**
@@ -119,39 +228,107 @@ function compareVersions(a: string, b: string): number {
   return aPatch - bPatch;
 }
 
-/** Detect the installed OpenSpec CLI version by running `openspec --version`. */
-export async function detectOpenSpecVersion(): Promise<{ version: string } | { error: string }> {
+/** Run a command at the repository root, resolving stdout+stderr or rejecting on failure. */
+function runAtRoot(root: string, command: string, args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    // Commands are typically .cmd shims on Windows; `shell: true` lets execFile find them on PATH
+    // across platforms without callers needing to know the extension.
+    execFile(
+      command,
+      args,
+      { cwd: root, shell: true, env: envWithLocalBin(root) },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(new Error(`${command} ${args.join(' ')} failed: ${error.message}`));
+          return;
+        }
+        resolve(`${stdout}${stderr}`);
+      },
+    );
+  });
+}
+
+/**
+ * Detect the installed OpenSpec CLI version by running `openspec --version`. When a repository
+ * root is given, its node_modules/.bin is consulted first, so a devDependency install counts.
+ */
+export async function detectOpenSpecVersion(
+  root?: string,
+): Promise<{ version: string } | { error: string }> {
   return new Promise((resolve) => {
     // `openspec` is typically a .cmd shim on Windows; `shell: true` lets execFile find it on PATH
     // across platforms without callers needing to know the extension.
-    execFile('openspec', ['--version'], { shell: true }, (error, stdout, stderr) => {
-      if (error) {
-        resolve({
-          error: `OpenSpec CLI not found on PATH (run: npm install -g openspec). ${error.message}`,
-        });
-        return;
-      }
-      const output = `${stdout}${stderr}`.trim();
-      // `openspec --version` prints something like "1.3.0" or "openspec/1.3.0 ...".
-      const match = output.match(/(\d+\.\d+\.\d+(?:-[^\s]+)?)/);
-      if (!match?.[1]) {
-        resolve({ error: `Could not parse OpenSpec version from output: ${output}` });
-        return;
-      }
-      resolve({ version: match[1] });
-    });
+    execFile(
+      'openspec',
+      ['--version'],
+      { shell: true, ...(root ? { env: envWithLocalBin(root) } : {}) },
+      (error, stdout, stderr) => {
+        if (error) {
+          resolve({
+            error: `OpenSpec CLI not found on PATH (run: npm install -g ${OPENSPEC_NPX_SPEC}). ${error.message}`,
+          });
+          return;
+        }
+        const output = `${stdout}${stderr}`.trim();
+        // `openspec --version` prints something like "1.3.0" or "openspec/1.3.0 ...".
+        const match = output.match(/(\d+\.\d+\.\d+(?:-[^\s]+)?)/);
+        if (!match?.[1]) {
+          resolve({ error: `Could not parse OpenSpec version from output: ${output}` });
+          return;
+        }
+        resolve({ version: match[1] });
+      },
+    );
   });
 }
 
-/** Check if an OpenSpec workspace exists at the given root (openspec/ directory present). */
-export async function isOpenSpecWorkspace(root: string): Promise<boolean> {
-  return exists(join(root, 'openspec'));
+/**
+ * Create an OpenSpec workspace at the root. Uses the installed CLI when one is on PATH (or in
+ * node_modules/.bin); otherwise runs the pinned OpenSpec major through npx, which downloads
+ * nothing permanent and never mutates the global environment. `--tools none` keeps the
+ * framework's own initializer non-interactive.
+ *
+ * Returns the CLI version that ran and whether it came through npx, so callers can pass the
+ * version on to `addOpenSpecIntegration` (nothing may be on PATH afterwards) and recommend a
+ * permanent install.
+ */
+export async function bootstrapOpenSpecWorkspace(
+  root: string,
+): Promise<{ version: string; viaNpx: boolean; command: string }> {
+  if (await isOpenSpecWorkspace(root)) {
+    throw new Error('An OpenSpec workspace already exists at this root.');
+  }
+  const detected = await detectOpenSpecVersion(root);
+  if (!('error' in detected)) {
+    if (compareVersions(detected.version, MIN_SUPPORTED_OPENSPEC) < 0) {
+      throw new Error(
+        `OpenSpec CLI version ${detected.version} is below the minimum supported ${MIN_SUPPORTED_OPENSPEC}. Please upgrade OpenSpec.`,
+      );
+    }
+    const command = 'openspec init --tools none';
+    await runAtRoot(root, 'openspec', ['init', '--tools', 'none']);
+    return { version: detected.version, viaNpx: false, command };
+  }
+  const command = `npx -y ${OPENSPEC_NPX_SPEC} init --tools none`;
+  await runAtRoot(root, 'npx', ['-y', OPENSPEC_NPX_SPEC, 'init', '--tools', 'none']);
+  // A second npx call resolves from the cache the first one populated.
+  const output = await runAtRoot(root, 'npx', ['-y', OPENSPEC_NPX_SPEC, '--version']);
+  const match = output.trim().match(/(\d+\.\d+\.\d+(?:-[^\s]+)?)/);
+  if (!match?.[1]) {
+    throw new Error(`Could not parse OpenSpec version from npx output: ${output.trim()}`);
+  }
+  return { version: match[1], viaNpx: true, command };
+}
+
+/** Check if the OpenSpec integration is installed (its metadata file is present). */
+export async function isOpenSpecIntegrationInstalled(root: string): Promise<boolean> {
+  return pathExists(metaPath(root));
 }
 
 /** Read and parse the existing openspec/config.yaml, or null if it does not exist. */
 export async function readOpenSpecConfig(root: string): Promise<Record<string, unknown> | null> {
   const path = configPath(root);
-  if (!(await exists(path))) return null;
+  if (!(await pathExists(path))) return null;
   const text = await readFile(path, 'utf8');
   const parsed = parse(text);
   if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
@@ -180,19 +357,29 @@ function extractPdacContext(context: string | undefined): string | null {
  *   (idempotent); otherwise the PDaC block is appended after a separator. User-authored context
  *   lines are never lost.
  * - `rules`: for each PDaC artifact (proposal, specs, design, tasks), PDaC rules are appended to
- *   existing rules, deduplicating identical entries.
- * - `operations`: PDaC apply/archive guidance is appended to existing guidance, deduplicating.
+ *   existing rules, deduplicating identical entries. Entries recorded as previously managed whose
+ *   wording is no longer current are removed first, so a guidance change replaces the old string
+ *   instead of accumulating next to it. User-authored entries are never removed.
+ * - `operations`: PDaC apply/archive guidance is appended to existing guidance, deduplicating,
+ *   with the same previously-managed replacement.
  * - Any other fields (githubCopilot, etc.) are preserved untouched.
  *
  * Returns the merged config and a list of human-readable change descriptions.
  */
-export function mergeConfig(existing: Record<string, unknown> | null): {
+export function mergeConfig(
+  existing: Record<string, unknown> | null,
+  previouslyManaged?: ManagedStrings,
+): {
   config: Record<string, unknown>;
   changes: string[];
 } {
   const config: Record<string, unknown> = { ...(existing ?? {}) };
   const changes: string[] = [];
 
+  // Strings PDaC injected in the past but no longer injects verbatim: remove before appending.
+  const staleManaged = (recorded: string[] | undefined, current: string[]): string[] =>
+    (recorded ?? []).filter((entry) => !current.includes(entry));
+
   // --- context ---
   const existingContext =
     typeof config['context'] === 'string' ? (config['context'] as string) : undefined;
@@ -223,22 +410,45 @@ export function mergeConfig(existing: Record<string, unknown> | null): {
       ? { ...(config['rules'] as Record<string, unknown>) }
       : {};
   let rulesChanged = false;
-  for (const [artifact, pdacRules] of Object.entries(PDAC_RULES)) {
+  let staleRulesRemoved = false;
+  const ruleArtifacts = new Set([
+    ...Object.keys(PDAC_RULES),
+    ...Object.keys(previouslyManaged?.rules ?? {}),
+  ]);
+  for (const artifact of ruleArtifacts) {
+    const pdacRules = PDAC_RULES[artifact] ?? [];
+    const stale = staleManaged(previouslyManaged?.rules[artifact], pdacRules);
     const existingList = Array.isArray(existingRules[artifact])
       ? [...(existingRules[artifact] as string[])]
       : [];
-    const merged = [...existingList];
+    const merged = existingList.filter((entry) => !stale.includes(entry));
+    if (merged.length !== existingList.length) {
+      staleRulesRemoved = true;
+      rulesChanged = true;
+    }
     for (const rule of pdacRules) {
       if (!merged.includes(rule)) {
         merged.push(rule);
         rulesChanged = true;
       }
     }
-    existingRules[artifact] = merged;
+    if (merged.length === 0) {
+      delete existingRules[artifact];
+    } else {
+      existingRules[artifact] = merged;
+    }
   }
   if (rulesChanged) {
-    config['rules'] = existingRules;
-    changes.push('Merged PDaC citation rules into openspec/config.yaml (rules:).');
+    if (Object.keys(existingRules).length === 0) {
+      delete config['rules'];
+    } else {
+      config['rules'] = existingRules;
+    }
+    changes.push(
+      staleRulesRemoved
+        ? 'Merged PDaC citation rules into openspec/config.yaml (rules:), replacing outdated PDaC entries.'
+        : 'Merged PDaC citation rules into openspec/config.yaml (rules:).',
+    );
   }
 
   // --- operations ---
@@ -249,8 +459,10 @@ export function mergeConfig(existing: Record<string, unknown> | null): {
       ? { ...(config['operations'] as Record<string, unknown>) }
       : {};
   let opsChanged = false;
+  let staleOpsRemoved = false;
   for (const opKey of ['apply', 'archive'] as const) {
     const pdacGuidance = PDAC_OPERATIONS[opKey].guidance;
+    const stale = staleManaged(previouslyManaged?.operations[opKey], pdacGuidance);
     const existingOp =
       existingOperations[opKey] &&
       typeof existingOperations[opKey] === 'object' &&
@@ -260,7 +472,11 @@ export function mergeConfig(existing: Record<string, unknown> | null): {
     const existingGuidance = Array.isArray(existingOp['guidance'])
       ? [...(existingOp['guidance'] as string[])]
       : [];
-    const merged = [...existingGuidance];
+    const merged = existingGuidance.filter((entry) => !stale.includes(entry));
+    if (merged.length !== existingGuidance.length) {
+      staleOpsRemoved = true;
+      opsChanged = true;
+    }
     for (const guidance of pdacGuidance) {
       if (!merged.includes(guidance)) {
         merged.push(guidance);
@@ -272,7 +488,11 @@ export function mergeConfig(existing: Record<string, unknown> | null): {
   }
   if (opsChanged) {
     config['operations'] = existingOperations;
-    changes.push('Merged PDaC operation guidance into openspec/config.yaml (operations:).');
+    changes.push(
+      staleOpsRemoved
+        ? 'Merged PDaC operation guidance into openspec/config.yaml (operations:), replacing outdated PDaC entries.'
+        : 'Merged PDaC operation guidance into openspec/config.yaml (operations:).',
+    );
   }
 
   return { config, changes };
@@ -280,7 +500,7 @@ export function mergeConfig(existing: Record<string, unknown> | null): {
 
 /** Serialize config back to YAML with a trailing newline. */
 export function serializeConfig(config: Record<string, unknown>): string {
-  return `${stringify(config)}\n`;
+  return `${stringify(config).trimEnd()}\n`;
 }
 
 /** Read the ProductShape version from the integration-openspec package.json. */
@@ -295,26 +515,42 @@ async function productshapeVersion(): Promise<string> {
  * Add the OpenSpec integration to a repository.
  *
  * - Detects the OpenSpec CLI version; rejects if not found or below MIN_SUPPORTED_OPENSPEC.
+ *   A caller that already ran the CLI (the init bootstrap) can pass `cliVersion` to skip the
+ *   probe: after an npx bootstrap nothing is on PATH, yet the version is known.
  * - Requires an existing `openspec/` workspace (run `openspec init` first).
  * - Merges PDaC guidance into `openspec/config.yaml`, preserving existing user configuration.
- * - Records metadata under `.product/integrations/openspec.json`.
+ * - Records metadata under `.product/integrations/openspec.json`, including the exact strings
+ *   injected, so a later update replaces outdated PDaC entries instead of accumulating them.
  * - Idempotent: running twice produces the same result.
  * - `--dry-run` reports what would change without writing.
  * - `--force` re-merges even if the PDaC block is already present (useful after a PDaC upgrade).
  */
 export async function addOpenSpecIntegration(
   root: string,
-  options: { force?: boolean; dryRun?: boolean } = {},
+  options: {
+    force?: boolean;
+    dryRun?: boolean;
+    cliVersion?: string;
+    /**
+     * The repository's configured `validation.warnings-as-errors` policy, reflected verbatim in
+     * the installed CI example so its blocking behaviour is stated, never silently changed.
+     */
+    warningsAsErrors?: boolean;
+  } = {},
 ): Promise<{ written: string[]; changes: string[]; meta: OpenSpecIntegrationMeta }> {
-  const { force = false, dryRun = false } = options;
+  const { force = false, dryRun = false, warningsAsErrors = false } = options;
 
-  const detected = await detectOpenSpecVersion();
-  if ('error' in detected) {
-    throw new Error(detected.error);
+  let openspecVersion = options.cliVersion;
+  if (!openspecVersion) {
+    const detected = await detectOpenSpecVersion(root);
+    if ('error' in detected) {
+      throw new Error(detected.error);
+    }
+    openspecVersion = detected.version;
   }
-  if (compareVersions(detected.version, MIN_SUPPORTED_OPENSPEC) < 0) {
+  if (compareVersions(openspecVersion, MIN_SUPPORTED_OPENSPEC) < 0) {
     throw new Error(
-      `OpenSpec CLI version ${detected.version} is below the minimum supported ${MIN_SUPPORTED_OPENSPEC}. Please upgrade OpenSpec.`,
+      `OpenSpec CLI version ${openspecVersion} is below the minimum supported ${MIN_SUPPORTED_OPENSPEC}. Please upgrade OpenSpec.`,
     );
   }
 
@@ -323,29 +559,36 @@ export async function addOpenSpecIntegration(
   }
 
   const existing = await readOpenSpecConfig(root);
+  const previousMeta = await readMeta(root);
 
-  // Detect a conflicting user context that is NOT the PDaC block and has no room for it.
-  // In practice we always append, so a "conflict" only arises if the user explicitly removed the
-  // PDaC block after a previous install and we are re-adding without --force.
-  if (!force && existing) {
-    const existingContext =
-      typeof existing['context'] === 'string' ? (existing['context'] as string) : undefined;
-    if (existingContext && extractPdacContext(existingContext) === null) {
-      // The user has context but no PDaC block. We will append, which is safe — not a conflict.
-    }
+  const { config, changes: configChanges } = mergeConfig(existing, previousMeta?.managed);
+
+  const ciDesired = renderCiExample({ warningsAsErrors });
+  const ciAbsolute = ciExamplePath(root);
+  const ciExisting = (await pathExists(ciAbsolute)) ? await readFile(ciAbsolute, 'utf8') : null;
+  const ciChanged = ciExisting !== ciDesired;
+
+  const changes = [...configChanges];
+  if (ciChanged) {
+    changes.push(
+      ciExisting === null
+        ? `Installed CI-ready verification example at ${CI_EXAMPLE_RELATIVE}.`
+        : `Updated CI-ready verification example at ${CI_EXAMPLE_RELATIVE}.`,
+    );
   }
 
-  const { config, changes } = mergeConfig(existing);
+  const meta: OpenSpecIntegrationMeta = {
+    provider: 'openspec',
+    version: await productshapeVersion(),
+    openspecVersion,
+    installedAt: new Date().toISOString(),
+    configPath: CONFIG_RELATIVE,
+    ciExamplePath: CI_EXAMPLE_RELATIVE,
+    managed: currentManagedStrings(),
+  };
 
   if (changes.length === 0 && !force) {
     // Already up to date. Still record/refresh metadata.
-    const meta: OpenSpecIntegrationMeta = {
-      provider: 'openspec',
-      version: await productshapeVersion(),
-      openspecVersion: detected.version,
-      installedAt: new Date().toISOString(),
-      configPath: CONFIG_RELATIVE,
-    };
     if (!dryRun) {
       await writeMeta(root, meta);
     }
@@ -354,33 +597,22 @@ export async function addOpenSpecIntegration(
 
   const written: string[] = [];
   if (!dryRun) {
-    const serialized = serializeConfig(config);
-    await mkdir(dirname(configPath(root)), { recursive: true });
-    await writeFile(configPath(root), serialized, 'utf8');
-    written.push(CONFIG_RELATIVE);
-
-    const meta: OpenSpecIntegrationMeta = {
-      provider: 'openspec',
-      version: await productshapeVersion(),
-      openspecVersion: detected.version,
-      installedAt: new Date().toISOString(),
-      configPath: CONFIG_RELATIVE,
-    };
+    if (configChanges.length > 0 || force) {
+      const serialized = serializeConfig(config);
+      await mkdir(dirname(configPath(root)), { recursive: true });
+      await writeFile(configPath(root), serialized, 'utf8');
+      written.push(CONFIG_RELATIVE);
+    }
+    if (ciChanged || force) {
+      await mkdir(dirname(ciAbsolute), { recursive: true });
+      await writeFile(ciAbsolute, ciDesired, 'utf8');
+      written.push(CI_EXAMPLE_RELATIVE);
+    }
     await writeMeta(root, meta);
     written.push(META_RELATIVE);
   }
 
-  return {
-    written,
-    changes,
-    meta: {
-      provider: 'openspec',
-      version: await productshapeVersion(),
-      openspecVersion: detected.version,
-      installedAt: new Date().toISOString(),
-      configPath: CONFIG_RELATIVE,
-    },
-  };
+  return { written, changes, meta };
 }
 
 /** Write the integration metadata file. */
@@ -393,7 +625,7 @@ async function writeMeta(root: string, meta: OpenSpecIntegrationMeta): Promise<v
 /** Read the integration metadata file, or null if absent. */
 async function readMeta(root: string): Promise<OpenSpecIntegrationMeta | null> {
   const path = metaPath(root);
-  if (!(await exists(path))) return null;
+  if (!(await pathExists(path))) return null;
   return JSON.parse(await readFile(path, 'utf8')) as OpenSpecIntegrationMeta;
 }
 
@@ -403,11 +635,15 @@ async function readMeta(root: string): Promise<OpenSpecIntegrationMeta | null> {
  */
 export async function updateOpenSpecIntegration(
   root: string,
-  options: { force?: boolean; dryRun?: boolean } = {},
+  options: { force?: boolean; dryRun?: boolean; warningsAsErrors?: boolean } = {},
 ): Promise<{ written: string[]; changes: string[] }> {
   // `add` already re-merges idempotently; `force` ensures the metadata is refreshed even when
   // the config content did not change.
-  const result = await addOpenSpecIntegration(root, { force: true, dryRun: options.dryRun });
+  const result = await addOpenSpecIntegration(root, {
+    force: true,
+    dryRun: options.dryRun,
+    warningsAsErrors: options.warningsAsErrors,
+  });
   return { written: result.written, changes: result.changes };
 }
 
@@ -425,7 +661,7 @@ export async function checkOpenSpecIntegration(root: string): Promise<{
   const checks: { name: string; ok: boolean; detail: string }[] = [];
 
   // 1. OpenSpec CLI installed and supported.
-  const detected = await detectOpenSpecVersion();
+  const detected = await detectOpenSpecVersion(root);
   if ('error' in detected) {
     checks.push({ name: 'openspec CLI', ok: false, detail: detected.error });
   } else if (compareVersions(detected.version, MIN_SUPPORTED_OPENSPEC) < 0) {
@@ -494,6 +730,21 @@ export async function checkOpenSpecIntegration(root: string): Promise<{
     });
   }
 
+  // 3b. CI-ready verification example present.
+  if (await pathExists(ciExamplePath(root))) {
+    checks.push({
+      name: 'ci example',
+      ok: true,
+      detail: `CI-ready verification example present at ${CI_EXAMPLE_RELATIVE}.`,
+    });
+  } else {
+    checks.push({
+      name: 'ci example',
+      ok: false,
+      detail: `CI-ready verification example missing (${CI_EXAMPLE_RELATIVE}). Run: prodshape integration update`,
+    });
+  }
+
   // 4. PDaC rules present.
   if (config) {
     const rules =
@@ -539,6 +790,30 @@ export async function removeOpenSpecIntegration(
   const { dryRun = false } = options;
   const removed: string[] = [];
 
+  // Remove both what the metadata recorded as injected and what the current guidance would
+  // inject: the union covers metadata written before the record existed as well as entries left
+  // behind by an older ProductShape.
+  const recorded = (await readMeta(root))?.managed;
+  const current = currentManagedStrings();
+  const managedRules: Record<string, string[]> = {};
+  for (const key of new Set([
+    ...Object.keys(current.rules),
+    ...Object.keys(recorded?.rules ?? {}),
+  ])) {
+    managedRules[key] = [
+      ...new Set([...(current.rules[key] ?? []), ...(recorded?.rules[key] ?? [])]),
+    ];
+  }
+  const managedOperations: Record<string, string[]> = {};
+  for (const key of new Set([
+    ...Object.keys(current.operations),
+    ...Object.keys(recorded?.operations ?? {}),
+  ])) {
+    managedOperations[key] = [
+      ...new Set([...(current.operations[key] ?? []), ...(recorded?.operations[key] ?? [])]),
+    ];
+  }
+
   const config = await readOpenSpecConfig(root);
   if (config !== null) {
     let configChanged = false;
@@ -569,7 +844,7 @@ export async function removeOpenSpecIntegration(
         : null;
     if (rules) {
       let rulesChanged = false;
-      for (const [artifact, pdacRules] of Object.entries(PDAC_RULES)) {
+      for (const [artifact, pdacRules] of Object.entries(managedRules)) {
         if (!Array.isArray(rules[artifact])) continue;
         const list = rules[artifact] as string[];
         const filtered = list.filter((r) => !pdacRules.includes(r));
@@ -600,7 +875,7 @@ export async function removeOpenSpecIntegration(
     if (operations) {
       let opsChanged = false;
       for (const opKey of ['apply', 'archive'] as const) {
-        const pdacGuidance = PDAC_OPERATIONS[opKey].guidance;
+        const pdacGuidance = managedOperations[opKey] ?? [];
         const op =
           operations[opKey] &&
           typeof operations[opKey] === 'object' &&
@@ -639,8 +914,16 @@ export async function removeOpenSpecIntegration(
     }
   }
 
+  // Remove the installed CI example.
+  if (await pathExists(ciExamplePath(root))) {
+    if (!dryRun) {
+      await rm(ciExamplePath(root), { force: true });
+    }
+    removed.push(CI_EXAMPLE_RELATIVE);
+  }
+
   // Remove metadata file.
-  if (await exists(metaPath(root))) {
+  if (await pathExists(metaPath(root))) {
     if (!dryRun) {
       await rm(metaPath(root), { force: true });
     }