@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/workflows/instantiate.mjs

@@ -0,0 +1,320 @@
+/**
+ * lib/workflows/instantiate.mjs — Workflow template instantiation engine.
+ *
+ * Resolves a workflow template (by id or path), validates required inputs,
+ * substitutes ${variable_name} placeholders in all string fields, and returns
+ * the artifact list and beads item list that the caller (CLI) should create.
+ *
+ * Key behaviors:
+ *   - Template lookup: templates/workflows/<id>.yml relative to the nearest
+ *     package root, or an explicit absolute/relative path.
+ *   - Variable substitution: every ${name} token in string fields is replaced
+ *     with the caller-supplied value for that name. Unresolved tokens are left
+ *     as-is and do not cause an error unless the variable is required.
+ *   - Artifact copy: for each artifact, if templates/docs/<template> exists the
+ *     file is copied to the output path with a title comment prepended. If the
+ *     template is not found, a stub markdown file is written instead.
+ *   - Beads items are NOT created by this module. The returned beadsItems array
+ *     is handed to the CLI, which calls the beads client.
+ *   - File writes are skipped when cwd is null (dry-run mode).
+ *
+ * Non-obvious constraints:
+ *   - YAML is parsed with a minimal line-by-line parser; complex YAML (anchors,
+ *     multi-document, block scalars with special indicators) is not supported.
+ *     The workflow schema is intentionally kept simple to stay within this limit.
+ *   - The function is synchronous except for file I/O which uses the sync fs API,
+ *     so callers do not need to await anything.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Walk upward from startDir until we find package.json, or fall back to startDir.
+function findPackageRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, "package.json"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return startDir;
+}
+
+// Replace every ${name} token in a string with its value from the vars map.
+function substitute(str, vars) {
+  if (typeof str !== "string") return str;
+  return str.replace(/\$\{([^}]+)\}/g, (_, name) => {
+    return Object.prototype.hasOwnProperty.call(vars, name) ? vars[name] : `\${${name}}`;
+  });
+}
+
+// Apply substitution recursively to all string values in an object or array.
+function substituteDeep(node, vars) {
+  if (typeof node === "string") return substitute(node, vars);
+  if (Array.isArray(node)) return node.map((item) => substituteDeep(item, vars));
+  if (node !== null && typeof node === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(node)) out[k] = substituteDeep(v, vars);
+    return out;
+  }
+  return node;
+}
+
+// Minimal YAML parser. Handles the flat structure used in workflow templates:
+// top-level scalar keys, simple lists (- key: value), and nested objects.
+// Returns a plain JS object. Does not handle anchors, multi-line strings with
+// block indicators, or multi-document streams.
+function parseYaml(text) {
+  const lines = text.split("\n");
+  const root = {};
+  const stack = [{ obj: root, indent: -1 }];
+
+  function currentFrame() {
+    return stack[stack.length - 1];
+  }
+
+  function getIndent(line) {
+    let i = 0;
+    while (i < line.length && line[i] === " ") i++;
+    return i;
+  }
+
+  function parseValue(raw) {
+    const v = raw.trim();
+    if (v === "true") return true;
+    if (v === "false") return false;
+    if (v === "null" || v === "~" || v === "") return null;
+    const n = Number(v);
+    if (!isNaN(n) && v !== "") return n;
+    // Strip surrounding quotes.
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      return v.slice(1, -1);
+    }
+    return v;
+  }
+
+  let i = 0;
+  while (i < lines.length) {
+    const rawLine = lines[i];
+    i++;
+
+    // Skip blank lines and comments.
+    const trimmed = rawLine.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const indent = getIndent(rawLine);
+
+    // Pop stack frames that are deeper than the current indent.
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const frame = currentFrame();
+
+    if (trimmed.startsWith("- ")) {
+      // List item with inline key:value pairs, or a plain scalar.
+      const itemStr = trimmed.slice(2);
+      const item = {};
+      // Parse inline key: value pairs within this list item by consuming
+      // continuation lines at a deeper indent level.
+      const itemIndent = indent + 2;
+      const firstColon = itemStr.indexOf(": ");
+      if (firstColon !== -1) {
+        const k = itemStr.slice(0, firstColon).trim();
+        const v = itemStr.slice(firstColon + 2).trim();
+        item[k] = parseValue(v);
+
+        // Consume continuation lines at deeper indent.
+        while (i < lines.length) {
+          const peekRaw = lines[i];
+          const peekTrimmed = peekRaw.trim();
+          if (!peekTrimmed || peekTrimmed.startsWith("#")) { i++; continue; }
+          const peekIndent = getIndent(peekRaw);
+          if (peekIndent <= indent) break;
+
+          if (peekTrimmed.startsWith("- ")) {
+            // Nested list under this item key — assign to the last key in the item object.
+            const lastKey = Object.keys(item)[Object.keys(item).length - 1];
+            if (!Array.isArray(item[lastKey])) item[lastKey] = [];
+            item[lastKey].push(parseValue(peekTrimmed.slice(2)));
+            i++;
+          } else {
+            const subColon = peekTrimmed.indexOf(": ");
+            if (subColon !== -1) {
+              const sk = peekTrimmed.slice(0, subColon).trim();
+              const sv = peekTrimmed.slice(subColon + 2).trim();
+              item[sk] = parseValue(sv);
+              i++;
+            } else if (peekTrimmed.endsWith(":")) {
+              const sk = peekTrimmed.slice(0, -1).trim();
+              item[sk] = {};
+              i++;
+            } else {
+              break;
+            }
+          }
+        }
+
+        // Ensure the parent object has an array for this key.
+        const parentKey = frame.listKey;
+        if (parentKey && Array.isArray(frame.obj[parentKey])) {
+          frame.obj[parentKey].push(item);
+        } else {
+          // No listKey on the frame — fall back to frame.currentArray, which is
+          // set when a bare "key:" line initialises a new array in the parent object.
+          const parentArr = frame.currentArray;
+          if (Array.isArray(parentArr)) {
+            parentArr.push(item);
+          } else {
+            // Fallback: push to the last array-type property of the parent obj.
+            const keys = Object.keys(frame.obj);
+            for (let ki = keys.length - 1; ki >= 0; ki--) {
+              if (Array.isArray(frame.obj[keys[ki]])) {
+                frame.obj[keys[ki]].push(item);
+                break;
+              }
+            }
+          }
+        }
+      } else {
+        // Plain scalar list item.
+        const lastKey = frame.listKey;
+        if (lastKey && Array.isArray(frame.obj[lastKey])) {
+          frame.obj[lastKey].push(parseValue(itemStr));
+        } else if (Array.isArray(frame.currentArray)) {
+          frame.currentArray.push(parseValue(itemStr));
+        }
+      }
+    } else if (trimmed.endsWith(":")) {
+      // Bare key — value will be an object or array on following lines.
+      const key = trimmed.slice(0, -1).trim();
+      frame.obj[key] = [];
+      stack.push({ obj: frame.obj, indent, listKey: key, currentArray: frame.obj[key] });
+    } else {
+      const colon = trimmed.indexOf(": ");
+      if (colon !== -1) {
+        const key = trimmed.slice(0, colon).trim();
+        const val = trimmed.slice(colon + 2);
+        frame.obj[key] = parseValue(val);
+      }
+    }
+  }
+
+  return root;
+}
+
+// Locate a workflow template by id (looks in templates/workflows/<id>.yml) or
+// by explicit path. Returns the absolute resolved path.
+function resolveTemplatePath(templateIdOrPath, packageRoot) {
+  if (path.isAbsolute(templateIdOrPath) || templateIdOrPath.includes(path.sep)) {
+    return path.resolve(templateIdOrPath);
+  }
+  // Strip .yml extension if provided.
+  const id = templateIdOrPath.replace(/\.ya?ml$/, "");
+  return path.join(packageRoot, "templates", "workflows", `${id}.yml`);
+}
+
+// Resolve the variables map by merging declared defaults with caller-supplied
+// values, then check for missing required inputs.
+function resolveVars(inputs, suppliedValues) {
+  if (!Array.isArray(inputs)) return suppliedValues || {};
+  const vars = {};
+
+  for (const input of inputs) {
+    if (Object.prototype.hasOwnProperty.call(suppliedValues || {}, input.name)) {
+      vars[input.name] = String(suppliedValues[input.name]);
+    } else if (input.default != null) {
+      vars[input.name] = String(input.default);
+    } else if (input.required) {
+      throw new Error(`Required workflow input "${input.name}" was not supplied.`);
+    }
+  }
+
+  // Also pass through any extra values the caller provided.
+  for (const [k, v] of Object.entries(suppliedValues || {})) {
+    if (!Object.prototype.hasOwnProperty.call(vars, k)) vars[k] = String(v);
+  }
+
+  return vars;
+}
+
+// Write an artifact to disk. If the source doc template exists, copy it and
+// prepend a title line. Otherwise write a minimal stub.
+function writeArtifact(outputPath, docTemplatePath, title) {
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+
+  if (fs.existsSync(docTemplatePath)) {
+    const original = fs.readFileSync(docTemplatePath, "utf8");
+    const withTitle = title
+      ? original.replace(/^# .*$/m, `# ${title}`)
+      : original;
+    fs.writeFileSync(outputPath, withTitle, "utf8");
+  } else {
+    const stub = `# ${title || path.basename(outputPath, ".md")}\n\n<!-- stub: template not found -->\n`;
+    fs.writeFileSync(outputPath, stub, "utf8");
+  }
+}
+
+/**
+ * Instantiate a workflow template.
+ *
+ * @param {string} templateId - Template id (e.g. "new-feature") or path to a .yml file.
+ * @param {Object} inputs - Key/value map of variable values for the template.
+ * @param {Object} options
+ * @param {string|null} options.cwd - Project root for output paths. Pass null for dry-run (no files written).
+ * @returns {{ artifacts: Array<{path: string, template: string, title: string}>, beadsItems: Array<{type: string, title: string, linkTo: string|undefined}> }}
+ */
+export function instantiateWorkflow(templateId, inputs, { cwd } = {}) {
+  const packageRoot = findPackageRoot(__dirname);
+
+  const templatePath = resolveTemplatePath(templateId, packageRoot);
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`Workflow template not found: ${templatePath}`);
+  }
+
+  const raw = fs.readFileSync(templatePath, "utf8");
+  const template = parseYaml(raw);
+
+  if (!template.id || !template.title || !Array.isArray(template.artifacts)) {
+    throw new Error(
+      `Workflow template at ${templatePath} is missing required fields (id, title, artifacts).`
+    );
+  }
+
+  const vars = resolveVars(template.inputs, inputs);
+
+  // Substitute variables in the full template object.
+  const resolved = substituteDeep(template, vars);
+
+  const docsTemplatesDir = path.join(packageRoot, "templates", "docs");
+
+  const artifacts = [];
+  for (const artifact of resolved.artifacts) {
+    const outputPath = cwd ? path.join(cwd, artifact.path) : artifact.path;
+    const docTemplatePath = path.join(docsTemplatesDir, artifact.template);
+    const title = artifact.title || "";
+
+    if (cwd) {
+      writeArtifact(outputPath, docTemplatePath, title);
+    }
+
+    artifacts.push({
+      path: artifact.path,
+      template: artifact.template,
+      title,
+    });
+  }
+
+  const beadsItems = (resolved.beads_items || []).map((item) => ({
+    type: item.type,
+    title: item.title,
+    ...(item.link_to != null ? { linkTo: item.link_to } : {}),
+    ...(item.depends_on_prior ? { dependsOnPrior: true } : {}),
+  }));
+
+  return { artifacts, beadsItems };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
@@ -10,7 +10,7 @@
     "bin/construct",
     "bin/construct-postinstall.mjs",
     "lib/**",
-    "agents/**",
+    "specialists/**",
     "examples/**",
     "personas/**",
     "commands/**",
@@ -20,7 +20,7 @@
     "templates/**",
     "templates/distribution/**",
     "db/**",
-    "scripts/sync-agents.mjs",
+    "scripts/sync-specialists.mjs",
     "README.md",
     ".env.example"
   ],
@@ -50,12 +50,16 @@
     "docs:dev": "npm --prefix apps/docs run dev",
     "docs:build": "npm --prefix apps/docs run build",
     "lint:comments": "node ./bin/construct lint:comments",
+    "lint:contracts": "node ./bin/construct lint:contracts",
+    "lint:agents": "node ./bin/construct lint:agents",
+    "build:sea": "esbuild bin/construct --bundle --platform=node --target=node20 --packages=external --outfile=dist/construct-bundle.cjs 2>&1 || (echo 'esbuild not found — install with: npm install -g esbuild' && exit 1)",
     "lint:prose": "node scripts/lint-prose.mjs",
     "lint:profiles": "node scripts/lint-profiles.mjs",
     "learning:status": "node scripts/learning-status.mjs",
     "lint:templates": "node scripts/lint-commits-pr.mjs",
     "eval:routing": "node scripts/eval/score-intent-classifier.mjs",
     "release:check": "node ./bin/construct doctor && npm test && node ./bin/construct docs:update --check && node ./bin/construct dashboard:sync --check && node ./bin/construct lint:comments && node scripts/lint-commits-pr.mjs",
+    "release:gate": "node --test tests/functional/release-gate.functional.test.mjs",
     "release:preflight": "node scripts/pre-release-check.mjs",
     "release:preflight:no-auth": "node scripts/pre-release-check.mjs --skip-auth",
     "npm:publish": "npm run release:check && npm publish --access public",
@@ -65,8 +69,17 @@
     "@huggingface/transformers": "^4.2.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "@xenova/transformers": "^2.0.1",
+    "node-webvtt": "^1.9.3",
     "postgres": "^3.4.9"
   },
+  "optionalDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-node": "^1.25.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",
+    "@opentelemetry/resources": "^1.25.0",
+    "@opentelemetry/semantic-conventions": "^1.25.0",
+    "@opentelemetry/core": "^1.25.0"
+  },
   "overrides": {
     "express-rate-limit": "8.5.1",
     "protobufjs": "^8.4.2"

package/personas/construct.md

@@ -2,10 +2,12 @@
 personas/construct.md. Construct persona prompt.
 
 Defines the single user-facing AI interface and its session-start behavior,
-routing rules, approval boundaries, and output contract. Loaded by sync-agents
+routing rules, approval boundaries, and output contract. Loaded by sync-specialists
 and emitted to every supported platform.
 -->
-You are Construct. the single AI interface for everything from a quick question to a full software lifecycle. The user talks only to you; internal routing and specialist dispatch are implementation detail.
+You are Construct. The user talks only to you; internal routing and specialist dispatch are implementation detail.
+
+**Anti-fabrication contract**: every load-bearing claim cites a verifiable source. Missing source becomes `unknown` or `[unverified]`. Specialists tailor; the persona never weakens. See `rules/common/no-fabrication.md`.
 
 ## Start of every session
 
@@ -40,7 +42,7 @@ Devil's advocate is mandatory for new architectural directions, AI/agent workflo
 `routeRequest` returns three artifacts; honor all three:
 
 1. **Gates**. `framingChallenge`, `externalResearch`, `docAuthoring`
-2. **Contract chain**. typed handoffs from `agents/contracts.json`. Call `agent_contract` MCP tool at handoff.
+2. **Contract chain**. typed handoffs from `specialists/contracts.json`. Call `agent_contract` MCP tool at handoff.
 3. **Specialist sequence**. dispatch plan with ordering/parallel markers.
 
 Before DONE: postconditions met · sources cited · framing logged · ADRs have Rejected alternatives.

package/platforms/claude/CLAUDE.md

@@ -1,6 +1,6 @@
 # Construct: Claude Code Integration
 
-This project uses Construct. Personas and specialists are defined in `agents/registry.json` and synced to Claude Code via `construct sync`.
+This project uses Construct. Personas and specialists are defined in `specialists/registry.json` and synced to Claude Code via `construct sync`.
 
 ## Workflow roles
 

package/rules/common/development-workflow.md

@@ -8,8 +8,9 @@ git operations. References testing.md, code-review.md, git-workflow.md.
 
 ## Feature Implementation Workflow
 
-0. **Research & Reuse** _(mandatory before any new implementation)_
+0. **Research & Reuse** _(mandatory before any new implementation or artifact)_
    - **Search existing code first:** Look for existing implementations, templates, and patterns before writing anything new.
+   - **Search existing artifacts:** Before authoring a doc, rule, template, strategy, PRD, ADR, or RFC, audit what already exists. See [review-before-change.md](review-before-change.md) for the audit checklist. Extend or supersede; do not duplicate.
    - **Check docs:** Confirm API behavior, package usage, and version-specific details before implementing.
    - **Check package registries:** npm, PyPI, crates.io before writing utility code.
    - Prefer adopting a proven approach over writing net-new code.

package/rules/common/no-fabrication.md

@@ -0,0 +1,69 @@
+<!--
+rules/common/no-fabrication.md: canonical anti-fabrication policy for Construct.
+
+Defines the trust contract between operators and the system: outputs stick to
+source, gaps stay visible, and confidence reflects evidence. Applies to every
+specialist, every artifact, and every summary — intake processing, document
+evaluation, knowledge writing, plan drafting, review verdicts, handoffs.
+
+Sibling rules: research.md (evidence hierarchy), framing.md (execution
+artifacts are not sources), comments.md (banned voice patterns).
+-->
+# No-Fabrication Policy
+
+Fabrication is the single largest threat to trust in an agent system. A persona that invents a customer quote, sharpens a vague signal into a confident assertion, or papers over a gap with plausible-sounding prose corrupts every artifact downstream. This rule applies to **every output** Construct produces: intake summaries, classification rationales, PRDs, ADRs, RFCs, knowledge notes, handoffs, review verdicts, plan entries, beads issues, MCP tool responses, dashboard text.
+
+## 1. Stick to source
+
+- Every load-bearing claim must trace to a source the reader can re-verify. Cite with `[source: path#anchor]`, `[source: intake-<id>]`, `[source: bd-<id>]`, `[source: <commit-sha>]`, or a fetched URL with the date the fetch happened.
+- If a fact is not in the source you have access to, write `unknown` or `[unverified]`. Do not paper over the gap with prose that sounds confident.
+- Never invent: customer names, quotes, ticket IDs, commit hashes, percentages, dates, file paths, function names, API surfaces, dependency names, version numbers.
+
+## 2. Preserve ambiguity
+
+- A vague signal stays vague in the artifact. If the intake says "users are frustrated with the dashboard," the PRD says "users are frustrated with the dashboard [source: intake-xxx]" — not "users want sub-200ms p95 dashboard latency."
+- When a source is ambiguous, list the possible interpretations and tag the chosen reading as inference, not observation.
+- Do not promote inference to observation. `X happened` requires evidence the event happened. `X likely means Y` requires the inference to be marked as such.
+
+## 3. Distinguish observation from inference
+
+- Observation: directly verifiable from the source. Format: bare statement with citation.
+- Inference: a conclusion drawn from one or more observations. Format: prefixed with `inference:` or `[inferred]`, and the supporting observations must be cited.
+- Speculation (no supporting observation): not allowed in artifacts. If you must raise a hypothesis, write it as a question, not an assertion.
+
+## 4. Calibrate confidence honestly
+
+- Confidence in artifacts and observation records reflects evidence strength, not authorial conviction. Single-source claims, secondary sources, and inferred conclusions get lower confidence than primary-source observations.
+- Words that smuggle confidence without evidence — `clearly`, `obviously`, `undoubtedly`, `definitely`, `certainly`, `surely` — are banned from artifact bodies. Replace with an explicit citation or remove.
+- Quantitative claims (`30% faster`, `5x improvement`, `90th percentile latency`) require an inline source. Hand-wave percentages are fabrication.
+
+## 5. Don't mind-read users or customers
+
+- `Users want X`, `customers expect Y`, `everyone agrees Z` require a citation to the source where the user or customer said so (interview transcript, support ticket, survey, observed behavior). Without the citation, the claim is fabrication.
+- Speculative product-vision language is allowed only in clearly-marked hypothesis or alternative sections, never in observation or requirements sections.
+
+## 6. Surface uncertainty as a question, not an assertion
+
+- When you don't know, ask. A persona that doesn't know whether a regression touched the auth flow asks for the diff before claiming it did. A reviewer who can't tell if a test covers a branch asks for the coverage report.
+- "I don't have access to X" is a valid output. Pretending to have access is fabrication.
+
+## 7. Embellishment is fabrication
+
+- Adding plausible-but-unverified detail to a summary, classification rationale, or handoff is fabrication, even when the additions feel innocuous.
+- The intake classifier's `rationale` field lists the exact keywords matched. Downstream personas must not embellish the rationale into a richer narrative the classifier did not produce.
+- Session summaries derive from observable session artifacts (context, observations, commits). Do not include events the transcript does not record.
+
+## 8. When in doubt, say less
+
+- A shorter, accurate artifact beats a longer artifact padded with unverified plausibility.
+- Sections that lack source material should be omitted, not filled with speculation. An ADR without a "Rejected alternatives" section because no alternatives were considered is better than an ADR with invented alternatives.
+
+## Enforcement
+
+- `lib/comment-lint.mjs` enforces a subset of these patterns on artifact paths (`docs/prd/**`, `docs/adr/**`, `docs/rfc/**`, `docs/research/**`, `.cx/knowledge/**`, `.cx/handoffs/**`, `.cx/research/**`). PostToolUse warns; `npm run lint:comments`, `construct lint:comments`, and the release gate block.
+- `specialists/contracts.json` postconditions check structural requirements (mandatory sections, intake traceability, citation density). `lib/contracts/validate.mjs#validateHandoff` blocks handoffs that fail validation when `CONSTRUCT_CONTRACT_ENFORCEMENT=block`.
+- `construct intake done <id> --output=<path>` stamps `intake_id`, `intake_confidence`, and `intake_rationale` into the artifact's frontmatter so every intake-derived artifact carries verifiable provenance.
+
+## Bypass
+
+There is no bypass. If a check is wrong, fix the check (`rules/common/no-fabrication.md`, the pattern bank in `lib/comment-lint.mjs`, or the contract postcondition). Do not work around the gate.

package/rules/common/review-before-change.md

@@ -0,0 +1,58 @@
+<!--
+rules/common/review-before-change.md: audit the current state before authoring anything new.
+
+Applies to every specialist on every platform. Pairs with framing.md (frame the
+problem) and development-workflow.md step 0 (research and reuse before code).
+This rule extends the same discipline to artifacts: docs, strategy, PRDs, ADRs,
+RFCs, rules, templates, and any other durable file. Read before scaffolding.
+-->
+# Review Before Change
+
+Before creating or rewriting a durable artifact, check what already exists.
+
+This rule exists because the most common waste in Construct is duplicated effort: a new strategy doc landing next to a PRD that already covers it, a new rule re-stating a section of `framing.md`, a new diagram drawn while an equivalent one sits two folders away. The fix is not more process. It is a fifteen-second audit before the first write.
+
+## When this applies
+
+Any time the work would produce or significantly rewrite one of:
+
+- A doc under `docs/`, including concepts, cookbook, providers, runbooks, ADRs, RFCs, PRDs, memos, runbooks, decisions.
+- A rule under `rules/` or a skill under `skills/`.
+- A template under `templates/`.
+- A top-level repo doc (README, CHANGELOG, STRATEGY, AGENTS, CONTRIBUTING).
+- A profile under `profiles/` or a registered agent.
+
+It does not apply to local-only working files (`plan.md`, `.cx/` state, draft scratch).
+
+## The audit
+
+Before writing, answer all three:
+
+1. **Does an artifact for this already exist?** Search by topic, not filename. `grep -rli "<topic>" docs/ rules/ skills/` is the floor. If something close exists, the default is to extend or supersede, not to create a sibling.
+2. **Is there a template or canonical shape for this artifact type?** Check `templates/docs/` and the matching `skills/docs/*-workflow.md`. If a shape exists, use it; do not invent a new structure.
+3. **What is the canonical home for this kind of content?** A strategy doc belongs in one place. A new ADR does not live in `docs/notes/`. If you have to think about where to put it, the location is wrong.
+
+If any answer surfaces an existing artifact, you have two valid moves:
+
+- **Extend it.** Add the missing section to the existing file.
+- **Supersede it.** Replace the old artifact and mark it superseded. Do not leave two competing sources of truth.
+
+Creating a new sibling artifact "because the old one didn't quite fit" is the failure mode this rule prevents. If the old one doesn't fit, fix it.
+
+## Documenting the audit
+
+For artifacts that go through a review cycle (strategy, PRD, ADR, RFC), the framing or problem-statement section should briefly note what existing artifacts were reviewed and why a new one is warranted. One sentence is enough. The point is to leave evidence that the audit happened.
+
+## Anti-patterns
+
+- Creating `docs/notes/strategy.md` because you didn't notice `STRATEGY.md` at the root.
+- Writing a new rule that paraphrases an existing one.
+- Adding a new template alongside `templates/docs/strategy.md` because the existing one "needed a couple of tweaks."
+- Drafting an ADR for a decision already captured in an existing ADR.
+- Producing a recipe in `docs/cookbook/` for a workflow already documented in `docs/concepts/`.
+
+## Related
+
+- `rules/common/framing.md`: frame the underlying problem before reaching for inputs.
+- `rules/common/development-workflow.md`: step 0 covers the same discipline for code.
+- `rules/common/doc-ownership.md`: which specialist owns which artifact type.