@prodshape/integration-openspec 0.1.0 → 0.4.0

package/dist/index.js

@@ -1,21 +1,220 @@
 // 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 pathExists(changesDir) ? 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.
+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 \u2014 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 \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 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}`;
 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."
+    "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 \u2014 the backlog item behind it, if there is one \u2014 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.",
@@ -27,36 +226,90 @@ 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,
+    "# - 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) {
-  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 +323,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 +407,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 +431,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 +491,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 +555,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 +579,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 +652,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 +690,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 +729,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 +753,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 +785,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 +801,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
 };