@prodshape/integration-openspec 0.1.0 → 0.3.1

package/dist/index.js

@@ -1,21 +1,217 @@
 // src/index.ts
-import { execFile } from "child_process";
-import { access, mkdir, readFile, rm, writeFile } from "fs/promises";
-import { dirname, join } from "path";
+import { execFile as execFile2 } from "child_process";
+import { mkdir, readFile as readFile2, rm, writeFile } from "fs/promises";
+import { dirname, join as join3 } from "path";
 import { parse, stringify } from "yaml";
+
+// src/workspace.ts
+import { access } from "fs/promises";
+import { join } from "path";
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isOpenSpecWorkspace(root) {
+  return pathExists(join(root, "openspec"));
+}
+function envWithLocalBin(root) {
+  const env = { ...process.env };
+  const separator = process.platform === "win32" ? ";" : ":";
+  let existing = "";
+  for (const key of Object.keys(env)) {
+    if (key.toUpperCase() === "PATH") {
+      existing = env[key] ?? "";
+      delete env[key];
+    }
+  }
+  const localBin = join(root, "node_modules", ".bin");
+  env["PATH"] = existing ? `${localBin}${separator}${existing}` : localBin;
+  return env;
+}
+
+// src/population.ts
+import { execFile } from "child_process";
+import { readdir, readFile } from "fs/promises";
+import { join as join2, relative, sep } from "path";
+import { promisify } from "util";
+import fg from "fast-glob";
+import { codes } from "@prodshape/core";
+var execFileAsync = promisify(execFile);
+var CHANGE_ARTIFACT_FILES = [
+  { file: "proposal.md", kind: "proposal" },
+  { file: "design.md", kind: "design" },
+  { file: "tasks.md", kind: "tasks" }
+];
+async function runOpenSpec(repoRoot, args) {
+  return execFileAsync("openspec", args, {
+    cwd: repoRoot,
+    shell: true,
+    env: envWithLocalBin(repoRoot),
+    maxBuffer: 10 * 1024 * 1024
+  });
+}
+async function openspecListChanges(repoRoot) {
+  try {
+    const { stdout } = await runOpenSpec(repoRoot, ["list", "--json"]);
+    const parsed = JSON.parse(stdout);
+    if (!Array.isArray(parsed.changes)) return null;
+    return parsed.changes.map((c) => c.name).filter((n) => typeof n === "string");
+  } catch {
+    return null;
+  }
+}
+async function isOpenSpecCliAvailable(repoRoot) {
+  try {
+    const { stdout } = await execFileAsync("openspec", ["--version"], {
+      shell: true,
+      ...repoRoot ? { env: envWithLocalBin(repoRoot) } : {}
+    });
+    return /\d+\.\d+\.\d+/.test(stdout);
+  } catch {
+    return false;
+  }
+}
+async function discoverMarkdownFiles(dir) {
+  const entries = await fg("**/*.md", {
+    cwd: dir,
+    absolute: true,
+    dot: false,
+    ignore: ["**/node_modules/**"]
+  });
+  return entries.map((e) => e.split("/").join(sep)).sort();
+}
+function buildConsumerDocument(absolutePath, repoRoot, opts) {
+  return {
+    path: relative(repoRoot, absolutePath).split(sep).join("/"),
+    absolutePath,
+    change: opts.change,
+    archived: opts.archived,
+    artifactKind: opts.artifactKind
+  };
+}
+async function discoverChangeDocuments(changeDir, repoRoot, change, archived) {
+  const docs = [];
+  for (const { file, kind } of CHANGE_ARTIFACT_FILES) {
+    const absolutePath = join2(changeDir, file);
+    try {
+      await readFile(absolutePath);
+      docs.push(
+        buildConsumerDocument(absolutePath, repoRoot, { change, archived, artifactKind: kind })
+      );
+    } catch {
+    }
+  }
+  const specsDir = join2(changeDir, "specs");
+  try {
+    const specFiles = await discoverMarkdownFiles(specsDir);
+    for (const absolutePath of specFiles) {
+      docs.push(
+        buildConsumerDocument(absolutePath, repoRoot, { change, archived, artifactKind: "specs" })
+      );
+    }
+  } catch {
+  }
+  return docs;
+}
+async function discoverSpecDocuments(specsDir, repoRoot) {
+  const docs = [];
+  try {
+    const specFiles = await discoverMarkdownFiles(specsDir);
+    for (const absolutePath of specFiles) {
+      docs.push(
+        buildConsumerDocument(absolutePath, repoRoot, { archived: false, artifactKind: "spec" })
+      );
+    }
+  } catch {
+  }
+  return docs;
+}
+async function discoverArchivedChanges(archiveDir) {
+  try {
+    const entries = await readdir(archiveDir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  } catch {
+    return [];
+  }
+}
+async function enumerateOpenSpecDocuments(repoRoot, options) {
+  const includeArchived = options?.includeArchived ?? false;
+  const root = join2(repoRoot, "openspec");
+  const changesDir = join2(root, "changes");
+  const archiveDir = join2(changesDir, "archive");
+  const specsDir = join2(root, "specs");
+  const documents = [];
+  const diagnostics = [];
+  let currentChangeNames = await openspecListChanges(repoRoot);
+  if (currentChangeNames === null) {
+    diagnostics.push({
+      severity: "error",
+      code: codes.openSpecCliMissing,
+      message: `OpenSpec CLI not available; the document population was enumerated by filesystem convention instead of 'openspec list'. Install with 'npm install -g @fission-ai/openspec@1' for authoritative population discovery.`,
+      file: "openspec/"
+    });
+    try {
+      const entries = await readdir(changesDir, { withFileTypes: true });
+      currentChangeNames = entries.filter((e) => e.isDirectory() && e.name !== "archive").map((e) => e.name).sort();
+    } catch {
+      currentChangeNames = [];
+    }
+  }
+  if (options?.change) {
+    const wanted = options.change;
+    if (currentChangeNames.includes(wanted)) {
+      currentChangeNames = [wanted];
+    } else {
+      currentChangeNames = [];
+    }
+  }
+  for (const name of currentChangeNames) {
+    const changeDir = join2(changesDir, name);
+    documents.push(...await discoverChangeDocuments(changeDir, repoRoot, name, false));
+  }
+  if (includeArchived) {
+    const archivedNames = await discoverArchivedChanges(archiveDir);
+    for (const name of archivedNames) {
+      if (options?.change && name !== options.change) continue;
+      const changeDir = join2(archiveDir, name);
+      documents.push(...await discoverChangeDocuments(changeDir, repoRoot, name, true));
+    }
+  }
+  documents.push(...await discoverSpecDocuments(specsDir, repoRoot));
+  return {
+    documents,
+    root: "openspec",
+    includeArchived,
+    diagnostics
+  };
+}
+var openSpecProvider = {
+  name: "openspec",
+  detectWorkspace: isOpenSpecWorkspace,
+  enumerateDocuments: enumerateOpenSpecDocuments
+};
+
+// src/index.ts
 var MIN_SUPPORTED_OPENSPEC = "1.0.0";
+var OPENSPEC_NPX_SPEC = "@fission-ai/openspec@1";
 var PDAC_CONTEXT_BEGIN = "<!-- pdac:context begin -->";
 var PDAC_CONTEXT_END = "<!-- pdac:context end -->";
 var 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.
+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 \u2014 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 current document population (archived changes excluded by default), so zero discovered citations is a set of failures, never a pass.
+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}`;
 var PDAC_RULES = {
   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."
+    "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.",
@@ -27,36 +223,86 @@ var PDAC_RULES = {
     "When a design decision depends on canonical product text, cite the artifact it depends on."
   ],
   tasks: [
-    "A task that changes cited behaviour must include a follow-up task to refresh the affected citations."
+    "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."
   ]
 };
 var 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."
     ]
   }
 };
+function currentManagedStrings() {
+  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]])
+    )
+  };
+}
 var CONFIG_RELATIVE = "openspec/config.yaml";
 var META_RELATIVE = ".product/integrations/openspec.json";
+var CI_EXAMPLE_RELATIVE = ".product/integrations/openspec.ci.yml";
+var OPENSPEC_META_RELATIVE = META_RELATIVE;
+var OPENSPEC_CI_EXAMPLE_RELATIVE = CI_EXAMPLE_RELATIVE;
+var OPENSPEC_VERIFY_COMMAND = "npx prodshape citations verify --provider openspec";
+function renderCiExample(options) {
+  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,
+    "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) {
-  return join(root, ...CONFIG_RELATIVE.split("/"));
+  return join3(root, ...CONFIG_RELATIVE.split("/"));
 }
 function metaPath(root) {
-  return join(root, ...META_RELATIVE.split("/"));
+  return join3(root, ...META_RELATIVE.split("/"));
 }
-async function exists(path) {
-  try {
-    await access(path);
-    return true;
-  } catch {
-    return false;
-  }
+function ciExamplePath(root) {
+  return join3(root, ...CI_EXAMPLE_RELATIVE.split("/"));
 }
 function compareVersions(a, b) {
   const parseParts = (v) => {
@@ -70,32 +316,77 @@ function compareVersions(a, b) {
   if (aMin !== bMin) return aMin - bMin;
   return aPatch - bPatch;
 }
-async function detectOpenSpecVersion() {
-  return new Promise((resolve) => {
-    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;
+function runAtRoot(root, command, args) {
+  return new Promise((resolve, reject) => {
+    execFile2(
+      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}`);
       }
-      const output = `${stdout}${stderr}`.trim();
-      const match = output.match(/(\d+\.\d+\.\d+(?:-[^\s]+)?)/);
-      if (!match?.[1]) {
-        resolve({ error: `Could not parse OpenSpec version from output: ${output}` });
-        return;
+    );
+  });
+}
+async function detectOpenSpecVersion(root) {
+  return new Promise((resolve) => {
+    execFile2(
+      "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();
+        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] });
       }
-      resolve({ version: match[1] });
-    });
+    );
   });
 }
-async function isOpenSpecWorkspace(root) {
-  return exists(join(root, "openspec"));
+async function bootstrapOpenSpecWorkspace(root) {
+  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 command2 = "openspec init --tools none";
+    await runAtRoot(root, "openspec", ["init", "--tools", "none"]);
+    return { version: detected.version, viaNpx: false, command: command2 };
+  }
+  const command = `npx -y ${OPENSPEC_NPX_SPEC} init --tools none`;
+  await runAtRoot(root, "npx", ["-y", OPENSPEC_NPX_SPEC, "init", "--tools", "none"]);
+  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 };
+}
+async function isOpenSpecIntegrationInstalled(root) {
+  return pathExists(metaPath(root));
 }
 async function readOpenSpecConfig(root) {
   const path = configPath(root);
-  if (!await exists(path)) return null;
-  const text = await readFile(path, "utf8");
+  if (!await pathExists(path)) return null;
+  const text = await readFile2(path, "utf8");
   const parsed = parse(text);
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
     return {};
@@ -109,9 +400,10 @@ function extractPdacContext(context) {
   if (begin === -1 || end === -1 || end < begin) return null;
   return context.slice(begin, end + PDAC_CONTEXT_END.length);
 }
-function mergeConfig(existing) {
+function mergeConfig(existing, previouslyManaged) {
   const config = { ...existing ?? {} };
   const changes = [];
+  const staleManaged = (recorded, current) => (recorded ?? []).filter((entry) => !current.includes(entry));
   const existingContext = typeof config["context"] === "string" ? config["context"] : void 0;
   const existingPdacBlock = extractPdacContext(existingContext);
   if (existingPdacBlock !== null) {
@@ -132,28 +424,55 @@ function mergeConfig(existing) {
   }
   const existingRules = config["rules"] && typeof config["rules"] === "object" && !Array.isArray(config["rules"]) ? { ...config["rules"] } : {};
   let rulesChanged = false;
-  for (const [artifact, pdacRules] of Object.entries(PDAC_RULES)) {
+  let staleRulesRemoved = false;
+  const ruleArtifacts = /* @__PURE__ */ 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]] : [];
-    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:)."
+    );
   }
   const existingOperations = config["operations"] && typeof config["operations"] === "object" && !Array.isArray(config["operations"]) ? { ...config["operations"] } : {};
   let opsChanged = false;
+  let staleOpsRemoved = false;
   for (const opKey of ["apply", "archive"]) {
     const pdacGuidance = PDAC_OPERATIONS[opKey].guidance;
+    const stale = staleManaged(previouslyManaged?.operations[opKey], pdacGuidance);
     const existingOp = existingOperations[opKey] && typeof existingOperations[opKey] === "object" && !Array.isArray(existingOperations[opKey]) ? { ...existingOperations[opKey] } : {};
     const existingGuidance = Array.isArray(existingOp["guidance"]) ? [...existingOp["guidance"]] : [];
-    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);
@@ -165,49 +484,63 @@ function mergeConfig(existing) {
   }
   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 };
 }
 function serializeConfig(config) {
-  return `${stringify(config)}
+  return `${stringify(config).trimEnd()}
 `;
 }
 async function productshapeVersion() {
   const packageJson = JSON.parse(
-    await readFile(new URL("../package.json", import.meta.url), "utf8")
+    await readFile2(new URL("../package.json", import.meta.url), "utf8")
   );
   return packageJson.version;
 }
 async function addOpenSpecIntegration(root, options = {}) {
-  const { force = false, dryRun = false } = options;
-  const detected = await detectOpenSpecVersion();
-  if ("error" in detected) {
-    throw new Error(detected.error);
+  const { force = false, dryRun = false, warningsAsErrors = false } = options;
+  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.`
     );
   }
   if (!await isOpenSpecWorkspace(root)) {
     throw new Error("No OpenSpec workspace found. Run `openspec init` first.");
   }
   const existing = await readOpenSpecConfig(root);
-  if (!force && existing) {
-    const existingContext = typeof existing["context"] === "string" ? existing["context"] : void 0;
-    if (existingContext && extractPdacContext(existingContext) === null) {
-    }
+  const previousMeta = await readMeta(root);
+  const { config, changes: configChanges } = mergeConfig(existing, previousMeta?.managed);
+  const ciDesired = renderCiExample({ warningsAsErrors });
+  const ciAbsolute = ciExamplePath(root);
+  const ciExisting = await pathExists(ciAbsolute) ? await readFile2(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 = {
+    provider: "openspec",
+    version: await productshapeVersion(),
+    openspecVersion,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    configPath: CONFIG_RELATIVE,
+    ciExamplePath: CI_EXAMPLE_RELATIVE,
+    managed: currentManagedStrings()
+  };
   if (changes.length === 0 && !force) {
-    const meta = {
-      provider: "openspec",
-      version: await productshapeVersion(),
-      openspecVersion: detected.version,
-      installedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      configPath: CONFIG_RELATIVE
-    };
     if (!dryRun) {
       await writeMeta(root, meta);
     }
@@ -215,31 +548,21 @@ async function addOpenSpecIntegration(root, options = {}) {
   }
   const written = [];
   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 = {
-      provider: "openspec",
-      version: await productshapeVersion(),
-      openspecVersion: detected.version,
-      installedAt: (/* @__PURE__ */ 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: (/* @__PURE__ */ new Date()).toISOString(),
-      configPath: CONFIG_RELATIVE
-    }
-  };
+  return { written, changes, meta };
 }
 async function writeMeta(root, meta) {
   const path = metaPath(root);
@@ -249,16 +572,20 @@ async function writeMeta(root, meta) {
 }
 async function readMeta(root) {
   const path = metaPath(root);
-  if (!await exists(path)) return null;
-  return JSON.parse(await readFile(path, "utf8"));
+  if (!await pathExists(path)) return null;
+  return JSON.parse(await readFile2(path, "utf8"));
 }
 async function updateOpenSpecIntegration(root, options = {}) {
-  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 };
 }
 async function checkOpenSpecIntegration(root) {
   const checks = [];
-  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) {
@@ -318,6 +645,19 @@ async function checkOpenSpecIntegration(root) {
       detail: `Integration recorded (OpenSpec ${meta.openspecVersion}, installed ${meta.installedAt}).`
     });
   }
+  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`
+    });
+  }
   if (config) {
     const rules = config["rules"] && typeof config["rules"] === "object" && !Array.isArray(config["rules"]) ? config["rules"] : {};
     const missingRules = [];
@@ -343,6 +683,26 @@ async function checkOpenSpecIntegration(root) {
 async function removeOpenSpecIntegration(root, options = {}) {
   const { dryRun = false } = options;
   const removed = [];
+  const recorded = (await readMeta(root))?.managed;
+  const current = currentManagedStrings();
+  const managedRules = {};
+  for (const key of /* @__PURE__ */ new Set([
+    ...Object.keys(current.rules),
+    ...Object.keys(recorded?.rules ?? {})
+  ])) {
+    managedRules[key] = [
+      .../* @__PURE__ */ new Set([...current.rules[key] ?? [], ...recorded?.rules[key] ?? []])
+    ];
+  }
+  const managedOperations = {};
+  for (const key of /* @__PURE__ */ new Set([
+    ...Object.keys(current.operations),
+    ...Object.keys(recorded?.operations ?? {})
+  ])) {
+    managedOperations[key] = [
+      .../* @__PURE__ */ new Set([...current.operations[key] ?? [], ...recorded?.operations[key] ?? []])
+    ];
+  }
   const config = await readOpenSpecConfig(root);
   if (config !== null) {
     let configChanged = false;
@@ -362,7 +722,7 @@ async function removeOpenSpecIntegration(root, options = {}) {
     const rules = config["rules"] && typeof config["rules"] === "object" && !Array.isArray(config["rules"]) ? config["rules"] : 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];
         const filtered = list.filter((r) => !pdacRules.includes(r));
@@ -386,7 +746,7 @@ async function removeOpenSpecIntegration(root, options = {}) {
     if (operations) {
       let opsChanged = false;
       for (const opKey of ["apply", "archive"]) {
-        const pdacGuidance = PDAC_OPERATIONS[opKey].guidance;
+        const pdacGuidance = managedOperations[opKey] ?? [];
         const op = operations[opKey] && typeof operations[opKey] === "object" && !Array.isArray(operations[opKey]) ? operations[opKey] : null;
         if (!op || !Array.isArray(op["guidance"])) continue;
         const list = op["guidance"];
@@ -418,7 +778,13 @@ async function removeOpenSpecIntegration(root, options = {}) {
       removed.push(CONFIG_RELATIVE);
     }
   }
-  if (await exists(metaPath(root))) {
+  if (await pathExists(ciExamplePath(root))) {
+    if (!dryRun) {
+      await rm(ciExamplePath(root), { force: true });
+    }
+    removed.push(CI_EXAMPLE_RELATIVE);
+  }
+  if (await pathExists(metaPath(root))) {
     if (!dryRun) {
       await rm(metaPath(root), { force: true });
     }
@@ -428,16 +794,27 @@ async function removeOpenSpecIntegration(root, options = {}) {
 }
 export {
   MIN_SUPPORTED_OPENSPEC,
+  OPENSPEC_CI_EXAMPLE_RELATIVE,
+  OPENSPEC_META_RELATIVE,
+  OPENSPEC_NPX_SPEC,
+  OPENSPEC_VERIFY_COMMAND,
   PDAC_CONTEXT_BLOCK,
   PDAC_OPERATIONS,
   PDAC_RULES,
   addOpenSpecIntegration,
+  bootstrapOpenSpecWorkspace,
   checkOpenSpecIntegration,
+  currentManagedStrings,
   detectOpenSpecVersion,
+  enumerateOpenSpecDocuments,
+  isOpenSpecCliAvailable,
+  isOpenSpecIntegrationInstalled,
   isOpenSpecWorkspace,
   mergeConfig,
+  openSpecProvider,
   readOpenSpecConfig,
   removeOpenSpecIntegration,
+  renderCiExample,
   serializeConfig,
   updateOpenSpecIntegration
 };