@codedrifters/configulator 0.0.274 → 0.0.276

package/lib/index.mjs

@@ -936,7 +936,7 @@ var agendaBundle = {
     {
       name: "agenda:finalize",
       color: "BFDADC",
-      description: "Phase 2: incorporate late-added items, register in the meetings index, cross-link related docs, and lock the agenda"
+      description: "Phase 2: register in meetings index, cross-link related docs, and lock the agenda before the meeting"
     }
   ]
 };
@@ -2783,442 +2783,6 @@ function assertValidProductContextPath(value) {
   }
 }
 
-// src/agent/bundles/workflow-diagrams.ts
-var DEFAULT_WORKFLOW_DIAGRAMS_ENABLED = true;
-var DEFAULT_WORKFLOW_DIAGRAMS_PATH = "docs/src/content/docs/agents/workflows.md";
-var DEFAULT_WORKFLOW_DIAGRAMS_BUNDLE_PATH_PATTERNS = [
-  "packages/@codedrifters/configulator/src/agent/bundles/**/*.ts",
-  ".claude/agents/**/*.md",
-  ".claude/skills/**/*.md"
-];
-var DEFAULT_WORKFLOW_DIAGRAMS_EMIT_STARTER = false;
-var DEFAULT_WORKFLOW_DIAGRAMS_EMIT_CHECKER = false;
-var DEFAULT_WORKFLOW_DIAGRAMS_REQUIRE_UPDATE = true;
-function resolveWorkflowDiagrams(config) {
-  const diagramsPath = config?.diagramsPath ?? DEFAULT_WORKFLOW_DIAGRAMS_PATH;
-  assertValidDiagramsPath(diagramsPath);
-  const bundlePathPatterns = config?.bundlePathPatterns ?? DEFAULT_WORKFLOW_DIAGRAMS_BUNDLE_PATH_PATTERNS;
-  assertValidBundlePathPatterns2(bundlePathPatterns);
-  return {
-    enabled: config?.enabled ?? DEFAULT_WORKFLOW_DIAGRAMS_ENABLED,
-    diagramsPath,
-    bundlePathPatterns,
-    emitStarterDiagram: config?.emitStarterDiagram ?? DEFAULT_WORKFLOW_DIAGRAMS_EMIT_STARTER,
-    emitChecker: config?.emitChecker ?? DEFAULT_WORKFLOW_DIAGRAMS_EMIT_CHECKER,
-    requireDiagramUpdate: config?.requireDiagramUpdate ?? DEFAULT_WORKFLOW_DIAGRAMS_REQUIRE_UPDATE
-  };
-}
-function validateWorkflowDiagramsConfig(config) {
-  return resolveWorkflowDiagrams(config);
-}
-function renderWorkflowDiagramsRuleContent(wd) {
-  if (!wd.enabled) {
-    return [
-      "# Workflow Diagrams",
-      "",
-      "**The workflow-diagrams convention is disabled in this project.**",
-      "Agents may change bundle or agent source files without updating",
-      "any diagrams page. When diagrams fall behind the prose, humans",
-      "must reconcile them manually.",
-      "",
-      "Enable the convention via",
-      "`AgentConfigOptions.workflowDiagrams.enabled = true`."
-    ].join("\n");
-  }
-  const requirementVerb = wd.requireDiagramUpdate ? "MUST" : "SHOULD";
-  const lines = [
-    "# Workflow Diagrams",
-    "",
-    "This project maintains a single hand-authored workflow-diagrams",
-    "page that visualises every agent's phases, its decision points,",
-    "and every cross-agent handoff. Prose scattered across rule files",
-    "and agent prompts describes each handoff in isolation; the",
-    "diagrams page is the single visual reference that shows the",
-    "whole pipeline at once.",
-    "",
-    "Diagrams are **hand-authored for readability**, not",
-    "auto-generated. A machine-generated graph of bundle dependencies",
-    "would technically stay in sync, but would not communicate the",
-    "intent behind each handoff \u2014 so the convention trades",
-    "auto-sync for editorial clarity and enforces sync via the rule",
-    "below.",
-    "",
-    "## Diagrams Page",
-    "",
-    `The workflow-diagrams page lives at \`${wd.diagramsPath}\`. It`,
-    "follows a stable structure so the sync rule can mechanically",
-    "identify which section matches which bundle:",
-    "",
-    "1. **Master cross-agent diagram** \u2014 one top-level Mermaid",
-    "   flowchart showing every agent as a node and every",
-    "   cross-agent issue-creation or file-consumption handoff as an",
-    "   edge.",
-    "2. **One section per agent / bundle** \u2014 a `## N. <agent-name>`",
-    "   heading followed by a single Mermaid `flowchart TD` diagram",
-    "   that depicts the agent's phase graph (nodes = phases /",
-    "   decisions, edges = transitions, styled end-nodes = commit /",
-    "   PR / done terminals).",
-    "3. **Legend** \u2014 a short table mapping colours and arrow styles",
-    "   to their meanings (dispatcher vs agent vs skill; solid vs",
-    "   dashed arrows for issue-creation vs file-consumption).",
-    "",
-    "Each agent section is independent. Changing one agent's phase",
-    "graph touches only that section; cross-agent handoff changes",
-    "touch the master diagram plus any affected agent sections.",
-    "",
-    "## Diagram-Touched-When-Bundle-Touched Rule",
-    "",
-    `Every change that modifies a bundle's phase graph ${requirementVerb}`,
-    `also update \`${wd.diagramsPath}\` in the same change set. The`,
-    "rule applies when **any** staged file in a commit or PR matches",
-    "one of the bundle-path patterns below:",
-    "",
-    ...wd.bundlePathPatterns.map((p) => `- \`${p}\``),
-    "",
-    "Mechanically: when a change set includes a file matching one of",
-    `the patterns above, it ${requirementVerb} also include a`,
-    `modification to \`${wd.diagramsPath}\`.`,
-    "",
-    "### What counts as a phase-graph change",
-    "",
-    "The rule targets edits that change **what the agent does**, not",
-    "stylistic tweaks. Concretely:",
-    "",
-    "- Adding, removing, or renaming a phase label.",
-    "- Changing a phase's inputs, outputs, or decision branches.",
-    "- Adding or removing a cross-agent handoff (an issue-creation",
-    "  or file-consumption edge between two bundles).",
-    "- Changing the sort order or priority logic that drives",
-    "  dispatcher routing between tiers.",
-    "",
-    "Edits that do **not** require a diagram update:",
-    "",
-    "- Typo fixes, comment tweaks, wording polish in rule prose.",
-    "- Refactors that preserve the exact phase / handoff graph",
-    "  (extracting a helper, renaming an internal variable,",
-    "  reordering imports).",
-    "- Updates to supporting metadata (permissions lists, default",
-    "  paths) that do not change the visible phase flow.",
-    "",
-    "When a change is borderline \u2014 the phase graph is unchanged but",
-    "the diagram's caption or annotation would be more accurate \u2014",
-    "err on the side of updating the diagram. The convention favours",
-    "over-updating over silent drift.",
-    "",
-    "## Authoring Checklist",
-    "",
-    "Authors and reviewers walk the following checklist before",
-    "merging any PR that touches a bundle path:",
-    "",
-    `1. **Did the phase graph change?** If yes, update \`${wd.diagramsPath}\``,
-    "   in the same PR \u2014 both the affected agent section and, if the",
-    "   change added or removed a cross-agent handoff, the master",
-    "   diagram.",
-    "2. **Did the diagram render?** Preview the Mermaid block locally",
-    "   (or via the docs site's dev server) and confirm it renders",
-    "   without syntax errors.",
-    `3. **Is the section heading stable?** Each agent section uses a`,
-    "   `## N. <agent-name>` heading where `<agent-name>` matches the",
-    "   bundle name / agent prompt filename. Keep the headings stable",
-    "   \u2014 downstream tooling may match on them.",
-    "4. **Does the legend still apply?** If a new arrow style or node",
-    "   colour was introduced, document it in the legend.",
-    ""
-  ];
-  if (wd.emitChecker) {
-    lines.push(
-      "## Automated Check",
-      "",
-      `The bundled \`.claude/procedures/check-workflow-diagrams.sh\``,
-      "helper enforces the rule mechanically. Given a set of changed",
-      "files (as a newline-separated list on stdin, or positional",
-      `arguments), it fails non-zero when any file matches a`,
-      `bundle-path pattern and \`${wd.diagramsPath}\` is not also in`,
-      "the list. Wire it into a pre-commit hook or CI job as needed:",
-      "",
-      "```bash",
-      "# Pre-commit (staged files):",
-      "git diff --cached --name-only \\",
-      "  | .claude/procedures/check-workflow-diagrams.sh",
-      "",
-      "# CI (branch-vs-base):",
-      "git diff --name-only origin/main...HEAD \\",
-      "  | .claude/procedures/check-workflow-diagrams.sh",
-      "```",
-      "",
-      "The helper exits with a descriptive diagnostic on failure, so",
-      "it plugs directly into any hook framework without further",
-      "glue. It exits `0` when no bundle files were touched or when",
-      "the diagrams file is also present in the change set.",
-      ""
-    );
-  }
-  lines.push(
-    "## Out of Scope",
-    "",
-    "The convention intentionally does not:",
-    "",
-    "- Auto-generate the diagrams \u2014 readability is the point.",
-    "- Enforce a specific Mermaid sub-grammar beyond `flowchart TD`",
-    "  for per-agent sections. Sequence diagrams, state diagrams, or",
-    "  class diagrams are fine for bespoke sections as long as they",
-    "  render.",
-    "- Gate every unrelated cleanup PR on a diagram touch. The rule",
-    "  targets phase-graph-affecting edits; pure cleanups documented",
-    "  as such are exempt."
-  );
-  return lines.join("\n");
-}
-function renderWorkflowDiagramsBundleHook(wd, bundleLabel) {
-  if (!wd.enabled) {
-    return "";
-  }
-  const verb = wd.requireDiagramUpdate ? "must" : "should";
-  return [
-    "## Workflow Diagram",
-    "",
-    `Every ${bundleLabel} change that modifies the phase graph,`,
-    "decision branches, or cross-agent handoffs documented by this",
-    `bundle ${verb} also update the matching section in`,
-    `\`${wd.diagramsPath}\` in the same PR. See the`,
-    "`workflow-diagrams-convention` rule for the full authoring",
-    "checklist, the path patterns the rule covers, and what counts",
-    "as a phase-graph change vs. a cosmetic edit."
-  ].join("\n");
-}
-function renderWorkflowDiagramsStarterPage(_wd) {
-  return [
-    "---",
-    "title: Agent Workflows",
-    "description: Hand-authored Mermaid diagrams for every agent pipeline and every cross-agent handoff.",
-    "---",
-    "",
-    "# Agent Workflows",
-    "",
-    "Each diagram shows every input, decision point, output path, and",
-    "downstream issue created by the agent. Solid arrows are issue-",
-    "creation handoffs; dashed arrows are file-consumption handoffs.",
-    "",
-    "Update this page in the same PR that changes a bundle's phase",
-    "graph \u2014 see the `workflow-diagrams-convention` rule for the full",
-    "contract.",
-    "",
-    "## Master Cross-Agent Diagram",
-    "",
-    "```mermaid",
-    "flowchart TB",
-    "    %% Replace the placeholder below with the real agent ecosystem.",
-    "    DISPATCHER[Dispatcher]",
-    "    AGENT_A[Agent A]",
-    "    AGENT_B[Agent B]",
-    "    DISPATCHER --> AGENT_A",
-    "    DISPATCHER --> AGENT_B",
-    "    AGENT_A -->|issue-creation| AGENT_B",
-    "    AGENT_B -.->|file-consumption| AGENT_A",
-    "```",
-    "",
-    "## 1. Example Agent",
-    "",
-    "```mermaid",
-    "flowchart TD",
-    "    START([Session Start]) --> CLAIM[Claim issue]",
-    "    CLAIM --> PHASE{Phase label?}",
-    "    PHASE -->|phase:a| A1[Phase A work]",
-    "    PHASE -->|phase:b| B1[Phase B work]",
-    "    A1 --> COMMIT[Commit & PR]",
-    "    B1 --> COMMIT",
-    "    COMMIT --> STOP([Stop])",
-    "    style STOP fill:#e8f5e9,stroke:#2e7d32",
-    "```",
-    "",
-    "## Legend",
-    "",
-    "| Style | Meaning |",
-    "|-------|---------|",
-    "| Solid arrow | Issue-creation handoff (agent A creates an issue for agent B) |",
-    "| Dashed arrow | File-consumption handoff (agent A reads files produced by agent B) |",
-    "| Green end-node | Terminal state (session complete) |"
-  ].join("\n");
-}
-function renderWorkflowDiagramsCheckerScript(wd) {
-  const patternsLiteral = wd.bundlePathPatterns.map((p) => `  ${JSON.stringify(p)}`).join("\n");
-  return [
-    "#!/usr/bin/env bash",
-    "# check-workflow-diagrams.sh \u2014 Enforce the diagram-touched-when-bundle-touched rule.",
-    "#",
-    "# Usage:",
-    "#   .claude/procedures/check-workflow-diagrams.sh <file>...",
-    "#   git diff --name-only HEAD | .claude/procedures/check-workflow-diagrams.sh",
-    "#",
-    "# Exits 0 when the workflow-diagrams page was touched alongside any",
-    "# bundle file in the change set, or when no bundle files were touched.",
-    "# Exits non-zero with a descriptive diagnostic on failure.",
-    "#",
-    "# The bundle-path patterns and diagrams path are rendered from the",
-    "# consumer's WorkflowDiagramsConfig at synth time \u2014 do not edit by",
-    "# hand; regenerate via `pnpm exec projen`.",
-    "#",
-    "# Patterns support the `**` recursive-segment wildcard even though",
-    "# bash's native `[[ $file == $glob ]]` pattern matching does not:",
-    "# each glob is converted to a POSIX-extended regex internally and",
-    "# matched with `=~`, so the script works uniformly on bash 3.2",
-    "# (macOS default) and bash 4+ (Linux / CI) without depending on",
-    "# `shopt -s globstar` (which only affects pathname expansion, not",
-    "# `[[ ]]` pattern matching).",
-    "",
-    "set -uo pipefail",
-    "",
-    "err() {",
-    '  printf "check-workflow-diagrams.sh: %s\\n" "$*" >&2',
-    "}",
-    "",
-    `diagrams_path=${JSON.stringify(wd.diagramsPath)}`,
-    "",
-    "# Bundle-path glob patterns. Translated to anchored POSIX-extended",
-    "# regexes at runtime by `glob_to_regex` below so `**` matches",
-    "# recursively across path segments.",
-    "bundle_patterns=(",
-    patternsLiteral,
-    ")",
-    "",
-    "# Convert a bash-style glob into an anchored POSIX-extended regex:",
-    "#   **/   \u2192 (.+/)?   (zero or more path segments plus trailing slash)",
-    "#   **    \u2192 .*       (anywhere, including `/`)",
-    "#   *     \u2192 [^/]*    (single path segment)",
-    "#   ?     \u2192 [^/]     (single non-slash char)",
-    "# Every other char is passed through, with regex metacharacters",
-    "# backslash-escaped so literal `.` / `+` / `(` etc. match themselves.",
-    "glob_to_regex() {",
-    '  local glob="$1"',
-    '  local regex=""',
-    "  local i=0",
-    "  local len=${#glob}",
-    "  while (( i < len )); do",
-    '    local c="${glob:i:1}"',
-    '    if [[ "$c" == "*" ]]; then',
-    '      local next="${glob:i+1:1}"',
-    '      if [[ "$next" == "*" ]]; then',
-    "        # `**` \u2014 recursive segment wildcard.",
-    '        local after="${glob:i+2:1}"',
-    '        if [[ "$after" == "/" ]]; then',
-    '          regex+="(.+/)?"',
-    "          i=$(( i + 3 ))",
-    "        else",
-    '          regex+=".*"',
-    "          i=$(( i + 2 ))",
-    "        fi",
-    "      else",
-    '        regex+="[^/]*"',
-    "        i=$(( i + 1 ))",
-    "      fi",
-    '    elif [[ "$c" == "?" ]]; then',
-    '      regex+="[^/]"',
-    "      i=$(( i + 1 ))",
-    "    else",
-    '      case "$c" in',
-    "        # Regex metacharacters \u2014 escape to match literally.",
-    "        '.'|'+'|'^'|'$'|'('|')'|'{'|'}'|'|'|'['|']'|'\\\\')",
-    '          regex+="\\\\$c"',
-    "          ;;",
-    "        *)",
-    '          regex+="$c"',
-    "          ;;",
-    "      esac",
-    "      i=$(( i + 1 ))",
-    "    fi",
-    "  done",
-    '  printf "^%s$" "$regex"',
-    "}",
-    "",
-    "# Collect the input file list: positional args override stdin.",
-    "if [[ $# -gt 0 ]]; then",
-    '  files=("$@")',
-    "else",
-    "  files=()",
-    "  while IFS= read -r line; do",
-    '    [[ -z "$line" ]] && continue',
-    '    files+=("$line")',
-    "  done",
-    "fi",
-    "",
-    "if [[ ${#files[@]} -eq 0 ]]; then",
-    "  # No input \u2014 nothing to check.",
-    "  exit 0",
-    "fi",
-    "",
-    "# Precompile each bundle pattern to a regex once.",
-    "bundle_regexes=()",
-    'for pattern in "${bundle_patterns[@]}"; do',
-    '  bundle_regexes+=("$(glob_to_regex "$pattern")")',
-    "done",
-    "",
-    "bundle_touched=0",
-    "matched_bundle=''",
-    "diagrams_touched=0",
-    "",
-    'for file in "${files[@]}"; do',
-    '  if [[ "$file" == "$diagrams_path" ]]; then',
-    "    diagrams_touched=1",
-    "    continue",
-    "  fi",
-    '  for regex in "${bundle_regexes[@]}"; do',
-    '    if [[ "$file" =~ $regex ]]; then',
-    "      bundle_touched=1",
-    '      matched_bundle="$file"',
-    "      break",
-    "    fi",
-    "  done",
-    "done",
-    "",
-    'if [[ "$bundle_touched" -eq 1 && "$diagrams_touched" -eq 0 ]]; then',
-    `  err "bundle file '$matched_bundle' was modified but '$diagrams_path' was not"`,
-    '  err "update the workflow-diagrams page in the same change set (see workflow-diagrams-convention rule)"',
-    "  exit 1",
-    "fi",
-    "",
-    "exit 0"
-  ].join("\n");
-}
-function assertValidDiagramsPath(value) {
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(
-      `WorkflowDiagramsConfig.diagramsPath must be a non-empty string; got ${JSON.stringify(
-        value
-      )}`
-    );
-  }
-  if (value.startsWith("/")) {
-    throw new Error(
-      `WorkflowDiagramsConfig.diagramsPath must be a repo-relative path (no leading '/'); got ${JSON.stringify(
-        value
-      )}`
-    );
-  }
-}
-function assertValidBundlePathPatterns2(value) {
-  if (!Array.isArray(value)) {
-    throw new Error(
-      `WorkflowDiagramsConfig.bundlePathPatterns must be an array; got ${JSON.stringify(
-        value
-      )}`
-    );
-  }
-  if (value.length === 0) {
-    throw new Error(
-      "WorkflowDiagramsConfig.bundlePathPatterns must not be empty \u2014 supply at least one pattern or omit the field to use the defaults"
-    );
-  }
-  for (const entry of value) {
-    if (typeof entry !== "string" || entry.trim().length === 0) {
-      throw new Error(
-        `WorkflowDiagramsConfig.bundlePathPatterns entries must be non-empty strings; got ${JSON.stringify(
-          entry
-        )}`
-      );
-    }
-  }
-}
-
 // src/agent/bundles/base.ts
 var createPackageSkill = {
   name: "create-package",
@@ -4296,16 +3860,6 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
         },
         tags: ["workflow"]
       },
-      {
-        name: "workflow-diagrams-convention",
-        description: `Workflow-diagrams convention: hand-authored Mermaid page under \`${paths.docsRoot}/agents/workflows.md\` with one diagram per agent plus a master cross-agent diagram, and the diagram-touched-when-bundle-touched rule that keeps the page in sync with every phase-graph or cross-agent-handoff change.`,
-        scope: AGENT_RULE_SCOPE.ALWAYS,
-        content: renderWorkflowDiagramsRuleContent(resolveWorkflowDiagrams()),
-        platforms: {
-          cursor: { exclude: true }
-        },
-        tags: ["workflow"]
-      },
       {
         name: "issue-templates-convention",
         description: `Issue-templates convention: a single hand-authored reference page under \`${paths.docsRoot}/agents/issue-templates.md\` that carries one canonical \`gh issue create\` recipe per downstream phase label, and the reference-don't-inline rule that keeps bundle rules and agent prompts citing that page instead of duplicating full template invocations.`,
@@ -5045,12 +4599,12 @@ function buildBcmWriterBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "bcm:context",
         color: "D4C5F9",
-        description: "Phase 3: fill Project Relevance, Value Stream Mapping, Enabling Software Systems, Roles Involved, and Company Size Applicability"
+        description: "Phase 3: fill Project Relevance, Value Stream Mapping, Software Systems, Roles, and Company Size"
       },
       {
         name: "bcm:connect",
         color: "FEF2C0",
-        description: "Phase 4: cross-link with parent/siblings, update registry and capability-map, open downstream research issues"
+        description: "Phase 4: cross-link parent/siblings, update registry and capability-map, open downstream issues"
       }
     ]
   };
@@ -6045,7 +5599,7 @@ function buildBusinessModelsBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "type:business-model",
         color: "5319E7",
-        description: "Work that authors or updates a Business Model Canvas plus BIZBOK value streams for an industry segment"
+        description: "Authors or updates a Business Model Canvas plus BIZBOK value streams for an industry segment"
       },
       {
         name: "business-models:scan",
@@ -8384,22 +7938,22 @@ function buildCustomerProfileBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "type:customer-profile",
         color: "5319E7",
-        description: "Work that researches a customer archetype: discovery across a scope, deep profile of one archetype, or feature-to-need competitor analysis for one archetype"
+        description: "Researches a customer archetype: discovery, deep profile, or competitor analysis"
       },
       {
         name: "customer:discover",
         color: "C5DEF5",
-        description: "Phase 1: scan existing documentation for customer archetype candidates and write a discovery report; create downstream profile issues"
+        description: "Phase 1: scan docs for archetype candidates, write discovery report, create profile issues"
       },
       {
         name: "customer:profile",
         color: "BFDADC",
-        description: "Phase 2: research one archetype in depth and populate the archetype page with segment, goals, jobs-to-be-done, constraints, buying process, and technology landscape"
+        description: "Phase 2: deep-research one archetype: segment, goals, JTBD, constraints, buying process, tech"
       },
       {
         name: "customer:competitors",
         color: "D4C5F9",
-        description: "Phase 3: map shared feature-matrix rows to archetype needs, identify unmet needs, and hand off req:scan seeds to the requirements-analyst bundle"
+        description: "Phase 3: map feature-matrix rows to archetype needs and hand off req:scan seeds"
       }
     ]
   };
@@ -8487,6 +8041,63 @@ function buildDocsSyncSubAgent(_paths) {
       "",
       "---",
       "",
+      "## Phase 1: Scan",
+      "",
+      "Phase 1 walks the repo, runs every registered drift check, and",
+      "writes a single combined **audit report** to disk. Phase 1 never",
+      "edits documentation \u2014 only the persisted report changes between",
+      "scan and fix.",
+      "",
+      "### Audit report",
+      "",
+      "The report shape is exported from `@codedrifters/configulator`",
+      "as `AuditReport` (under `src/docs-sync/scan/`) so Phase 2 and",
+      "any downstream consumers share one definition. Reports are",
+      "persisted at:",
+      "",
+      "```",
+      ".claude/state/docs-sync/<issue-number>-audit.json",
+      "```",
+      "",
+      "Every report carries a `schemaVersion`, the `issueNumber`, the",
+      "invocation `mode` (`pr` or `audit`), the `generatedAt` UTC",
+      "timestamp, the `repoRoot`, and an optional `scope` label, plus",
+      "two parallel views of the findings:",
+      "",
+      "- **`categories`** \u2014 findings grouped by drift-check category.",
+      "  Every category key is always present; empty arrays are",
+      "  persisted explicitly. The five categories are `apiDiff`,",
+      "  `tsdocCoverage`, `referenceMismatches`, `linkFailures`, and",
+      "  `sampleFailures`.",
+      "- **`findings`** \u2014 the same records re-aggregated as a single",
+      "  flat array, sorted by severity (`blocking` first), then",
+      "  category, file, line, and subject. Provided so consumers",
+      "  that don't need the category grouping can iterate one array",
+      "  and see the merge-blocking findings at the top.",
+      "",
+      "Every finding carries a `category`, `severity`",
+      "(`mechanical` / `advisory` / `blocking`), `location`, `subject`,",
+      "`details`, and an optional `fixHint` for the Phase 2 fix agent.",
+      "",
+      "### Orchestrator",
+      "",
+      "The scan is driven by `runScan(...)` (also exported under",
+      "`src/docs-sync/scan/`). The orchestrator accepts a list of",
+      "`AuditCheckRunner` instances, invokes each one in registration",
+      "order, merges the findings into the report, and (optionally)",
+      "persists the report to disk. The default check list is empty \u2014",
+      "this skeleton release runs cleanly with no checks registered",
+      "and produces a schema-compliant report whose category arrays",
+      "are all empty.",
+      "",
+      "Children of the parent docs-sync epic plug runners into the",
+      "orchestrator: API/TSDoc/reference checks land first, link",
+      "and fenced-sample checks land second, the fix phase reads the",
+      "persisted report, and the audit-mode walker reuses the same",
+      "report shape.",
+      "",
+      "---",
+      "",
       "## Write Boundaries",
       "",
       "Even once the pipeline is wired, the following boundaries are",
@@ -9209,22 +8820,22 @@ function buildDocsSyncBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "docs-sync:scan",
         color: "C5DEF5",
-        description: "Phase 1: scan code and docs for drift (API diff, TSDoc coverage, reference integrity, link integrity, code-sample compilation)"
+        description: "Phase 1: scan for drift (API diff, TSDoc coverage, references, links, sample compilation)"
       },
       {
         name: "docs-sync:fix",
         color: "BFDADC",
-        description: "Phase 2: apply mechanical idempotent fixes (TSDoc stubs, dead-link updates, registry sync, rename-follow) and file docs:write follow-ups for conceptual changes"
+        description: "Phase 2: apply mechanical fixes and file docs:write follow-ups for conceptual changes"
       },
       {
         name: "docs-sync:advisory",
         color: "FBCA04",
-        description: "Drift detected by docs-sync but does not block the PR; surfaced as a non-blocking note on the sticky comment"
+        description: "Drift detected by docs-sync but does not block the PR; surfaced as a sticky-comment note"
       },
       {
         name: "docs-sync:blocking",
         color: "B60205",
-        description: "Drift detected by docs-sync blocks the PR; applied together with review:human-required so pr-reviewer owns the merge gate"
+        description: "Drift blocks the PR; applied with review:human-required so pr-reviewer owns the merge gate"
       }
     ]
   };
@@ -10819,7 +10430,7 @@ function buildMaintenanceAuditBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "maint:verify",
         color: "D4C5F9",
-        description: "Phase 3: re-run the scan checks scoped to the paths the fix phase touched, compare pre/post findings, and close or re-queue the parent scan"
+        description: "Phase 3: re-run scan checks scoped to fix-phase paths, compare findings, close or re-queue scan"
       }
     ]
   };
@@ -15358,7 +14969,7 @@ function buildPeopleProfileBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "people:followup",
         color: "D4C5F9",
-        description: "Phase 3: cross-link the profile to existing companies, software, and meeting notes, and enqueue follow-up research issues for unprofiled companies and software products"
+        description: "Phase 3: cross-link profile to companies/software/meetings; enqueue follow-up research issues"
       },
       {
         name: "people:refresh",
@@ -18158,22 +17769,22 @@ function buildRegulatoryResearchBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "type:regulatory-research",
         color: "5319E7",
-        description: "Work that researches a regulatory compliance obligation: scan of a jurisdictional landscape, deep-dive on one regulation, or impact analysis against the consuming project"
+        description: "Researches a regulatory obligation: jurisdictional scan, deep-dive, or impact analysis"
       },
       {
         name: "regulatory:scan",
         color: "C5DEF5",
-        description: "Phase 1: enumerate regulations applicable to an industry, jurisdiction, or platform scope; write a scan report; create downstream research issues"
+        description: "Phase 1: enumerate regulations for an industry/jurisdiction/scope; create research issues"
       },
       {
         name: "regulatory:research",
         color: "BFDADC",
-        description: "Phase 2: research one regulation in depth and populate the regulation page with scope, triggers, requirements, jurisdiction variations, enforcement, and penalties"
+        description: "Phase 2: research one regulation in depth (scope, triggers, requirements, enforcement)"
       },
       {
         name: "regulatory:impact",
         color: "D4C5F9",
-        description: "Phase 3: assess product impact against one regulation and hand off actionable obligations as SEC req:scan seeds to the requirements-analyst bundle"
+        description: "Phase 3: assess product impact and hand off SEC req:scan seeds to requirements-analyst"
       }
     ]
   };
@@ -21450,7 +21061,7 @@ function buildRequirementsWriterBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "tier:customer-workflow",
         color: "EDEDED",
-        description: "Architectural tier: customer-configured workflow (business logic tenants configure within the platform)"
+        description: "Architectural tier: customer-configured workflow (business logic tenants configure)"
       },
       {
         name: "tier:consumer-app",
@@ -22850,7 +22461,7 @@ function buildRequirementsReviewerBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "req:deprecate",
         color: "D93F0B",
-        description: "Phase: transition existing requirement documents to Deprecated or Superseded using the requirements-reviewer skill"
+        description: "Phase: transition requirement docs to Deprecated/Superseded via the requirements-reviewer"
       }
     ]
   };
@@ -24504,7 +24115,7 @@ function buildSoftwareProfileBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "type:software-profile",
         color: "0E8A16",
-        description: "Work that produces or maintains a software profile, research notes, feature-matrix rows, or capability mappings"
+        description: "Produces a software profile, research notes, feature-matrix rows, or capability mappings"
       },
       {
         name: "software:research",
@@ -24524,12 +24135,12 @@ function buildSoftwareProfileBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "software:map",
         color: "A2EEEF",
-        description: "Phase 4: map each feature back to the BCM capability model, write the mapping onto the profile, and enqueue `bcm:outline` issues for unmapped features above the configured threshold"
+        description: "Phase 4: map features to the BCM model and enqueue bcm:outline issues for unmapped features"
       },
       {
         name: "software:followup",
         color: "FBCA04",
-        description: "Phase 5: enqueue follow-up research issues for adjacent products, the vendor company, and primary-attribution people surfaced in the profile"
+        description: "Phase 5: enqueue follow-up research for adjacent products, vendor company, and key people"
       }
     ]
   };
@@ -25856,32 +25467,32 @@ function buildStandardsResearchBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "type:standards-research",
         color: "5319E7",
-        description: "Work that researches an interoperability standard: version research, cross-version comparison, extension analysis, or standards-body organization profiling"
+        description: "Researches an interoperability standard: versions, comparison, extension, or org profile"
       },
       {
         name: "standards:scope",
         color: "C5DEF5",
-        description: "Phase 1: plan the research campaign for one standard; write the query plan; create downstream research, compare, and organizations issues"
+        description: "Phase 1: plan a standard's research campaign; write query plan; create downstream issues"
       },
       {
         name: "standards:research",
         color: "BFDADC",
-        description: "Phase 2: research one version of the standard and populate the version page with status, key changes, resources, adoption, and governance touch-points"
+        description: "Phase 2: research one version (status, key changes, resources, adoption, governance)"
       },
       {
         name: "standards:compare",
         color: "D4C5F9",
-        description: "Phase 3: synthesize a cross-version comparison on the standard's overview page \u2014 version timeline, maturity progression, breaking changes, migration paths"
+        description: "Phase 3: synthesize cross-version comparison: timeline, maturity, breaking changes, migration"
       },
       {
         name: "standards:extension",
         color: "FBCA04",
-        description: "Phase 4: analyze the extension mechanism needed for one domain entity whose base-spec mapping is Partial or Gap; hand off a Proposed ADR to the requirements pipeline"
+        description: "Phase 4: analyze extension for one Partial/Gap entity; hand off Proposed ADR to requirements"
       },
       {
         name: "standards:organizations",
         color: "0E8A16",
-        description: "Phase 5: profile one standards-body organization's role in the standard; hand off canonical company and people profiles to the profile bundles"
+        description: "Phase 5: profile one standards-body organization; hand off company/people profile issues"
       }
     ]
   };
@@ -26943,8 +26554,8 @@ var FALLBACKS = {
   monorepoLayoutSeedBlock: ""
 };
 var TEMPLATE_RE = /\{\{(\w+(?:\.\w+)*)\}\}/g;
-function getNestedValue(obj, path6) {
-  const parts = path6.split(".");
+function getNestedValue(obj, path7) {
+  const parts = path7.split(".");
   let current = obj;
   for (const part of parts) {
     if (current == null || typeof current !== "object") {
@@ -27170,20 +26781,20 @@ var ClaudeRenderer = class _ClaudeRenderer {
       obj.excludedCommands = [...sandbox.excludedCommands];
     }
     if (sandbox.filesystem) {
-      const fs3 = {};
+      const fs4 = {};
       if (sandbox.filesystem.allowRead?.length) {
-        fs3.allowRead = [...sandbox.filesystem.allowRead];
+        fs4.allowRead = [...sandbox.filesystem.allowRead];
       }
       if (sandbox.filesystem.denyRead?.length) {
-        fs3.denyRead = [...sandbox.filesystem.denyRead];
+        fs4.denyRead = [...sandbox.filesystem.denyRead];
       }
       if (sandbox.filesystem.allowWrite?.length) {
-        fs3.allowWrite = [...sandbox.filesystem.allowWrite];
+        fs4.allowWrite = [...sandbox.filesystem.allowWrite];
       }
       if (sandbox.filesystem.denyWrite?.length) {
-        fs3.denyWrite = [...sandbox.filesystem.denyWrite];
+        fs4.denyWrite = [...sandbox.filesystem.denyWrite];
       }
-      if (Object.keys(fs3).length > 0) obj.filesystem = fs3;
+      if (Object.keys(fs4).length > 0) obj.filesystem = fs4;
     }
     if (sandbox.network) {
       const net = {};
@@ -27639,26 +27250,6 @@ var SKILL_EVALS_BUNDLE_HOOKS = [
   ["requirements-analyst-workflow", "requirements-analyst"],
   ["requirements-writer-workflow", "write-requirement"]
 ];
-var WORKFLOW_DIAGRAMS_BUNDLE_HOOKS = [
-  ["bcm-writer-workflow", "bcm-writer"],
-  ["business-models-workflow", "business-models"],
-  ["company-profile-workflow", "company-profile"],
-  ["customer-profile-workflow", "customer-profile"],
-  ["industry-discovery-workflow", "industry-discovery"],
-  ["maintenance-audit-workflow", "maintenance-audit"],
-  ["meeting-agenda-workflow", "agenda"],
-  ["meeting-processing-workflow", "meeting-analysis"],
-  ["orchestrator-conventions", "orchestrator"],
-  ["people-profile-workflow", "people-profile"],
-  ["pr-review-workflow", "pr-review"],
-  ["regulatory-research-workflow", "regulatory-research"],
-  ["requirements-analyst-workflow", "requirements-analyst"],
-  ["requirements-reviewer-workflow", "requirements-reviewer"],
-  ["requirements-writer-workflow", "requirements-writer"],
-  ["research-pipeline-workflow", "research-pipeline"],
-  ["software-profile-workflow", "software-profile"],
-  ["standards-research-workflow", "standards-research"]
-];
 var ISSUE_TEMPLATES_BUNDLE_HOOKS = [
   ["bcm-writer-workflow", "bcm-writer"],
   ["business-models-workflow", "business-models"],
@@ -27830,24 +27421,6 @@ var AgentConfig = class _AgentConfig extends Component8 {
         executable: true
       });
     }
-    const resolvedWorkflowDiagrams = validateWorkflowDiagramsConfig(
-      this.options.workflowDiagrams
-    );
-    if (resolvedWorkflowDiagrams.enabled) {
-      if (resolvedWorkflowDiagrams.emitChecker) {
-        new TextFile4(this, ".claude/procedures/check-workflow-diagrams.sh", {
-          lines: renderWorkflowDiagramsCheckerScript(
-            resolvedWorkflowDiagrams
-          ).split("\n"),
-          executable: true
-        });
-      }
-      if (resolvedWorkflowDiagrams.emitStarterDiagram) {
-        new SampleFile(this.project, resolvedWorkflowDiagrams.diagramsPath, {
-          contents: renderWorkflowDiagramsStarterPage(resolvedWorkflowDiagrams)
-        });
-      }
-    }
     const resolvedIssueTemplates = validateIssueTemplatesConfig(
       this.options.issueTemplates
     );
@@ -28160,46 +27733,6 @@ ${hook}`
 
 ---
 
-${hook}`
-        });
-      }
-    }
-    const resolvedWorkflowDiagramsForRules = resolveWorkflowDiagrams(
-      this.options.workflowDiagrams
-    );
-    if (this.options.workflowDiagrams) {
-      const workflowDiagramsRule = ruleMap.get("workflow-diagrams-convention");
-      if (workflowDiagramsRule) {
-        const workflowDiagramsContent = renderWorkflowDiagramsRuleContent(
-          resolvedWorkflowDiagramsForRules
-        );
-        if (workflowDiagramsContent !== workflowDiagramsRule.content) {
-          ruleMap.set("workflow-diagrams-convention", {
-            ...workflowDiagramsRule,
-            content: workflowDiagramsContent
-          });
-        }
-      }
-    }
-    if (resolvedWorkflowDiagramsForRules.enabled) {
-      for (const [ruleName, label] of WORKFLOW_DIAGRAMS_BUNDLE_HOOKS) {
-        const existing = ruleMap.get(ruleName);
-        if (!existing) {
-          continue;
-        }
-        const hook = renderWorkflowDiagramsBundleHook(
-          resolvedWorkflowDiagramsForRules,
-          label
-        );
-        if (hook.length === 0) {
-          continue;
-        }
-        ruleMap.set(ruleName, {
-          ...existing,
-          content: `${existing.content}
-
----
-
 ${hook}`
         });
       }
@@ -29392,8 +28925,405 @@ function formatDiagnostic(d) {
   return `${code}${text}`.trim();
 }
 
-// src/docs-sync/tsdoc-coverage/coverage.ts
+// src/docs-sync/scan/audit-report.ts
+var AuditCategory = {
+  /**
+   * Findings produced by the public-API diff check that surfaces
+   * added, renamed, or removed exports between the current branch
+   * and the recorded baseline. Wired in by child issue #519.
+   */
+  ApiDiff: "apiDiff",
+  /**
+   * Findings produced by the TSDoc-coverage check that flags public
+   * exports without a one-sentence summary. Wired in by child issue
+   * #519.
+   */
+  TsdocCoverage: "tsdocCoverage",
+  /**
+   * Findings produced by the doc-reference cross-index check that
+   * flags inline-code symbol mentions whose target is missing or
+   * has changed. Wired in by child issue #519.
+   */
+  ReferenceMismatches: "referenceMismatches",
+  /**
+   * Findings produced by the link-integrity check (internal via
+   * `astro check`, external via `lychee`). Wired in by child issue
+   * #520.
+   */
+  LinkFailures: "linkFailures",
+  /**
+   * Findings produced by the fenced-sample compilation check that
+   * flags ` ```ts ` / ` ```typescript ` / ` ```tsx ` blocks in the
+   * docs that fail `tsc`. Wired in by child issue #520.
+   */
+  SampleFailures: "sampleFailures"
+};
+var AuditSeverity = {
+  /**
+   * The finding has a deterministic mechanical fix that the Phase 2
+   * (Fix) agent will auto-apply (TSDoc stubs, dead-link updates,
+   * registry sync, etc.).
+   */
+  Mechanical: "mechanical",
+  /**
+   * The finding deserves human attention but does not block the PR.
+   * Surfaced as a non-blocking note on the sticky `## Docs sync`
+   * comment.
+   */
+  Advisory: "advisory",
+  /**
+   * The finding blocks the PR. Per the parent epic this is reserved
+   * for the two narrow cases of confirmed broken external links and
+   * fenced TS samples that fail to compile.
+   */
+  Blocking: "blocking"
+};
+var AuditMode = {
+  Pr: "pr",
+  Audit: "audit"
+};
+var DOCS_SYNC_AUDIT_SCHEMA_VERSION = 1;
+function auditReportJsonSchema() {
+  const locationSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["file", "line"],
+    properties: {
+      file: { type: "string" },
+      line: { type: "integer", minimum: 0 }
+    }
+  };
+  const findingBaseProperties = {
+    severity: { type: "string", enum: ["mechanical", "advisory", "blocking"] },
+    location: locationSchema,
+    subject: { type: "string" },
+    details: { type: "string" },
+    fixHint: { type: "string" }
+  };
+  const apiDiffFindingSchema = {
+    type: "object",
+    required: [
+      "category",
+      "severity",
+      "location",
+      "subject",
+      "details",
+      "change",
+      "symbol"
+    ],
+    properties: {
+      ...findingBaseProperties,
+      category: { type: "string", const: "apiDiff" },
+      change: { type: "string", enum: ["added", "removed", "changed"] },
+      symbol: { type: "string" }
+    }
+  };
+  const tsdocCoverageFindingSchema = {
+    type: "object",
+    required: [
+      "category",
+      "severity",
+      "location",
+      "subject",
+      "details",
+      "shortfall",
+      "symbol"
+    ],
+    properties: {
+      ...findingBaseProperties,
+      category: { type: "string", const: "tsdocCoverage" },
+      shortfall: {
+        type: "string",
+        enum: [
+          "missing-summary",
+          "thin-summary",
+          "missing-params",
+          "missing-returns"
+        ]
+      },
+      symbol: { type: "string" }
+    }
+  };
+  const referenceMismatchFindingSchema = {
+    type: "object",
+    required: [
+      "category",
+      "severity",
+      "location",
+      "subject",
+      "details",
+      "mismatch",
+      "symbol"
+    ],
+    properties: {
+      ...findingBaseProperties,
+      category: { type: "string", const: "referenceMismatches" },
+      mismatch: {
+        type: "string",
+        enum: ["unknown-symbol", "signature-changed"]
+      },
+      symbol: { type: "string" }
+    }
+  };
+  const linkFailureFindingSchema = {
+    type: "object",
+    required: [
+      "category",
+      "severity",
+      "location",
+      "subject",
+      "details",
+      "url",
+      "kind",
+      "reason"
+    ],
+    properties: {
+      ...findingBaseProperties,
+      category: { type: "string", const: "linkFailures" },
+      url: { type: "string" },
+      kind: { type: "string", enum: ["internal", "external"] },
+      reason: { type: "string" }
+    }
+  };
+  const sampleFailureFindingSchema = {
+    type: "object",
+    required: [
+      "category",
+      "severity",
+      "location",
+      "subject",
+      "details",
+      "fenceIndex",
+      "lang",
+      "diagnostics"
+    ],
+    properties: {
+      ...findingBaseProperties,
+      category: { type: "string", const: "sampleFailures" },
+      fenceIndex: { type: "integer", minimum: 0 },
+      lang: { type: "string" },
+      diagnostics: { type: "array", items: { type: "string" } }
+    }
+  };
+  return {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    title: "DocsSyncAuditReport",
+    type: "object",
+    additionalProperties: false,
+    required: [
+      "schemaVersion",
+      "issueNumber",
+      "mode",
+      "generatedAt",
+      "repoRoot",
+      "scope",
+      "categories",
+      "findings"
+    ],
+    properties: {
+      schemaVersion: { type: "integer", const: DOCS_SYNC_AUDIT_SCHEMA_VERSION },
+      issueNumber: { type: "integer", minimum: 0 },
+      mode: { type: "string", enum: ["pr", "audit"] },
+      generatedAt: { type: "string", format: "date-time" },
+      repoRoot: { type: "string" },
+      scope: { type: "string" },
+      categories: {
+        type: "object",
+        additionalProperties: false,
+        required: [
+          "apiDiff",
+          "tsdocCoverage",
+          "referenceMismatches",
+          "linkFailures",
+          "sampleFailures"
+        ],
+        properties: {
+          apiDiff: { type: "array", items: apiDiffFindingSchema },
+          tsdocCoverage: { type: "array", items: tsdocCoverageFindingSchema },
+          referenceMismatches: {
+            type: "array",
+            items: referenceMismatchFindingSchema
+          },
+          linkFailures: { type: "array", items: linkFailureFindingSchema },
+          sampleFailures: { type: "array", items: sampleFailureFindingSchema }
+        }
+      },
+      findings: {
+        type: "array",
+        items: {
+          oneOf: [
+            apiDiffFindingSchema,
+            tsdocCoverageFindingSchema,
+            referenceMismatchFindingSchema,
+            linkFailureFindingSchema,
+            sampleFailureFindingSchema
+          ]
+        }
+      }
+    }
+  };
+}
+
+// src/docs-sync/scan/run-scan.ts
+import * as fs3 from "fs";
 import * as path5 from "path";
+var DEFAULT_AUDIT_REPORT_DIR = ".claude/state/docs-sync";
+var SEVERITY_RANK = {
+  blocking: 0,
+  advisory: 1,
+  mechanical: 2
+};
+var AUDIT_CATEGORY_ORDER = [
+  AuditCategory.ApiDiff,
+  AuditCategory.TsdocCoverage,
+  AuditCategory.ReferenceMismatches,
+  AuditCategory.LinkFailures,
+  AuditCategory.SampleFailures
+];
+function runScan(options) {
+  const repoRoot = path5.resolve(options.repoRoot);
+  const mode = options.mode;
+  const scope = options.scope ?? "";
+  const issueNumber = options.issueNumber;
+  const checks = options.checks ?? [];
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const persist = options.persist ?? false;
+  const reportDir = options.reportDir ?? DEFAULT_AUDIT_REPORT_DIR;
+  const context = {
+    repoRoot,
+    mode,
+    scope,
+    issueNumber
+  };
+  const collected = [];
+  for (const check of checks) {
+    const result = check.run(context);
+    for (const finding of result) {
+      collected.push(finding);
+    }
+  }
+  const report = buildReport({
+    issueNumber,
+    mode,
+    scope,
+    repoRoot,
+    generatedAt: now,
+    findings: collected
+  });
+  let reportPath = "";
+  if (persist) {
+    reportPath = persistAuditReport({
+      report,
+      repoRoot,
+      reportDir
+    });
+  }
+  return { report, reportPath };
+}
+function buildReport(args) {
+  const buckets = emptyCategoryBuckets();
+  for (const finding of args.findings) {
+    pushIntoBucket(buckets, finding);
+  }
+  buckets.apiDiff.sort(compareFindings);
+  buckets.tsdocCoverage.sort(compareFindings);
+  buckets.referenceMismatches.sort(compareFindings);
+  buckets.linkFailures.sort(compareFindings);
+  buckets.sampleFailures.sort(compareFindings);
+  const flat = [];
+  for (const key of AUDIT_CATEGORY_ORDER) {
+    const bucket = buckets[key];
+    for (const finding of bucket) {
+      flat.push(finding);
+    }
+  }
+  flat.sort(compareFindings);
+  return {
+    schemaVersion: DOCS_SYNC_AUDIT_SCHEMA_VERSION,
+    issueNumber: args.issueNumber,
+    mode: args.mode,
+    generatedAt: args.generatedAt.toISOString(),
+    repoRoot: args.repoRoot,
+    scope: args.scope,
+    categories: {
+      apiDiff: buckets.apiDiff,
+      tsdocCoverage: buckets.tsdocCoverage,
+      referenceMismatches: buckets.referenceMismatches,
+      linkFailures: buckets.linkFailures,
+      sampleFailures: buckets.sampleFailures
+    },
+    findings: flat
+  };
+}
+function persistAuditReport(args) {
+  const repoRoot = path5.resolve(args.repoRoot);
+  const reportDir = args.reportDir ?? DEFAULT_AUDIT_REPORT_DIR;
+  const targetDir = path5.resolve(repoRoot, reportDir);
+  fs3.mkdirSync(targetDir, { recursive: true });
+  const targetFile = path5.join(
+    targetDir,
+    `${args.report.issueNumber}-audit.json`
+  );
+  const tempFile = `${targetFile}.tmp-${process.pid}-${Date.now()}`;
+  const serialized = `${JSON.stringify(args.report, null, 2)}
+`;
+  fs3.writeFileSync(tempFile, serialized, "utf-8");
+  fs3.renameSync(tempFile, targetFile);
+  return targetFile;
+}
+function emptyCategoryBuckets() {
+  return {
+    apiDiff: [],
+    tsdocCoverage: [],
+    referenceMismatches: [],
+    linkFailures: [],
+    sampleFailures: []
+  };
+}
+function pushIntoBucket(buckets, finding) {
+  switch (finding.category) {
+    case AuditCategory.ApiDiff:
+      buckets.apiDiff.push(finding);
+      return;
+    case AuditCategory.TsdocCoverage:
+      buckets.tsdocCoverage.push(finding);
+      return;
+    case AuditCategory.ReferenceMismatches:
+      buckets.referenceMismatches.push(finding);
+      return;
+    case AuditCategory.LinkFailures:
+      buckets.linkFailures.push(finding);
+      return;
+    case AuditCategory.SampleFailures:
+      buckets.sampleFailures.push(finding);
+      return;
+    default: {
+      const exhaustive = finding;
+      throw new Error(
+        `runScan: unrecognized finding category: ${JSON.stringify(exhaustive)}`
+      );
+    }
+  }
+}
+function compareFindings(a, b) {
+  const sevDelta = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+  if (sevDelta !== 0) {
+    return sevDelta;
+  }
+  if (a.category !== b.category) {
+    return a.category.localeCompare(b.category);
+  }
+  if (a.location.file !== b.location.file) {
+    return a.location.file.localeCompare(b.location.file);
+  }
+  if (a.location.line !== b.location.line) {
+    return a.location.line - b.location.line;
+  }
+  return a.subject.localeCompare(b.subject);
+}
+
+// src/docs-sync/tsdoc-coverage/coverage.ts
+import * as path6 from "path";
 import { TSDocParser } from "@microsoft/tsdoc";
 import * as ts2 from "typescript";
 var TsDocCoverageKind = {
@@ -29411,8 +29341,8 @@ var DEFAULT_THIN_SUMMARY_WORD_THRESHOLD = 4;
 var DEFAULT_ENTRY_POINT = "src/index.ts";
 function analyzeTsDocCoverage(options) {
   const resolvedOptions = typeof options === "string" ? { packageRoot: options } : options;
-  const packageRoot = path5.resolve(resolvedOptions.packageRoot);
-  const entryPoint = path5.resolve(
+  const packageRoot = path6.resolve(resolvedOptions.packageRoot);
+  const entryPoint = path6.resolve(
     packageRoot,
     resolvedOptions.entryPoint ?? DEFAULT_ENTRY_POINT
   );
@@ -29475,7 +29405,7 @@ function analyzeTsDocCoverage(options) {
 }
 function resolveCompilerOptions(packageRoot, tsconfigPath) {
   if (tsconfigPath) {
-    const absoluteTsconfig = path5.resolve(packageRoot, tsconfigPath);
+    const absoluteTsconfig = path6.resolve(packageRoot, tsconfigPath);
     const configFile = ts2.readConfigFile(absoluteTsconfig, ts2.sys.readFile);
     if (configFile.error) {
       throw new Error(
@@ -29485,7 +29415,7 @@ function resolveCompilerOptions(packageRoot, tsconfigPath) {
     const parsed = ts2.parseJsonConfigFileContent(
       configFile.config,
       ts2.sys,
-      path5.dirname(absoluteTsconfig)
+      path6.dirname(absoluteTsconfig)
     );
     return { ...parsed.options, noEmit: true };
   }
@@ -29949,8 +29879,8 @@ var ResetTask = class _ResetTask extends Component14 {
     const resetTask = this.project.tasks.addTask(this.taskName, {
       description: "Delete build artifacts specified by pathsToRemove option, or artifactsDirectory if pathsToRemove is empty"
     });
-    this.pathsToRemove.forEach((path6) => {
-      resetTask.exec(`[ -e "${path6}" ] && rm -rf ${path6} || true`);
+    this.pathsToRemove.forEach((path7) => {
+      resetTask.exec(`[ -e "${path7}" ] && rm -rf ${path7} || true`);
     });
     const rootHasTurbo = TurboRepo.of(this.project.root) !== void 0;
     const isSubproject = this.project !== this.project.root;
@@ -30292,6 +30222,7 @@ var DEFAULT_TYPE_LABELS = [
 ];
 var DEFAULT_WORKFLOW_NAME2 = "sync-labels";
 var LABELS_CONFIG_PATH = ".github/labels.yml";
+var MAX_LABEL_DESCRIPTION_LENGTH = 100;
 function addSyncLabelsWorkflow(project, options) {
   const workflowName = options.workflowName ?? DEFAULT_WORKFLOW_NAME2;
   const deleteOtherLabels = options.deleteOtherLabels ?? true;
@@ -30314,6 +30245,18 @@ function addSyncLabelsWorkflow(project, options) {
     labelMap.set(label.name, label);
   }
   const allLabels = [...labelMap.values()];
+  const overlength = allLabels.filter(
+    (l) => (l.description ?? "").length > MAX_LABEL_DESCRIPTION_LENGTH
+  );
+  if (overlength.length > 0) {
+    const offenders = overlength.map(
+      (l) => `  - ${l.name} (${(l.description ?? "").length} chars): ${l.description}`
+    ).join("\n");
+    throw new Error(
+      `The following label descriptions exceed GitHub's ${MAX_LABEL_DESCRIPTION_LENGTH}-char limit and would break the sync-labels workflow:
+${offenders}`
+    );
+  }
   new LabelsFile(project, allLabels);
   const workflow = project.github?.addWorkflow(workflowName);
   if (!workflow) {
@@ -31892,11 +31835,15 @@ export {
   AGENT_RULE_SCOPE,
   AGENT_TIER_ROLES,
   AGENT_TIER_VALUES,
+  AUDIT_CATEGORY_ORDER,
   AgentConfig,
   ApiExtractor,
   AstroConfig,
   AstroOutput,
   AstroProject,
+  AuditCategory,
+  AuditMode,
+  AuditSeverity,
   AwsCdkProject,
   AwsDeployWorkflow,
   AwsDeploymentConfig,
@@ -31912,6 +31859,7 @@ export {
   DEFAULT_API_EXTRACTOR_ENTRY_POINT,
   DEFAULT_API_EXTRACTOR_REPORT_FILENAME,
   DEFAULT_API_EXTRACTOR_REPORT_FOLDER,
+  DEFAULT_AUDIT_REPORT_DIR,
   DEFAULT_DECOMPOSITION_TEMPLATE,
   DEFAULT_DELEGATE_TO_PR_REVIEWER,
   DEFAULT_DISPATCH_MODEL,
@@ -31953,15 +31901,11 @@ export {
   DEFAULT_TYPE_LABELS,
   DEFAULT_UNBLOCK_COMMENT_TEMPLATE,
   DEFAULT_UNBLOCK_DEPENDENTS_ENABLED,
-  DEFAULT_WORKFLOW_DIAGRAMS_BUNDLE_PATH_PATTERNS,
-  DEFAULT_WORKFLOW_DIAGRAMS_EMIT_CHECKER,
-  DEFAULT_WORKFLOW_DIAGRAMS_EMIT_STARTER,
-  DEFAULT_WORKFLOW_DIAGRAMS_ENABLED,
-  DEFAULT_WORKFLOW_DIAGRAMS_PATH,
-  DEFAULT_WORKFLOW_DIAGRAMS_REQUIRE_UPDATE,
+  DOCS_SYNC_AUDIT_SCHEMA_VERSION,
   JsiiFaker,
   LAYOUT_ENFORCEMENT,
   LAYOUT_ROOT_BY_PROJECT_TYPE,
+  MAX_LABEL_DESCRIPTION_LENGTH,
   MCP_TRANSPORT,
   MERGE_METHODS,
   MIMIMUM_RELEASE_AGE,
@@ -32000,6 +31944,7 @@ export {
   addSyncLabelsWorkflow,
   agendaBundle,
   analyzeTsDocCoverage,
+  auditReportJsonSchema,
   awsCdkBundle,
   baseBundle,
   bcmWriterBundle,
@@ -32016,6 +31961,7 @@ export {
   buildOrchestratorConventionsContent,
   buildPeopleProfileBundle,
   buildRegulatoryResearchBundle,
+  buildReport,
   buildRequirementsAnalystBundle,
   buildRequirementsReviewerBundle,
   buildRequirementsWriterBundle,
@@ -32032,6 +31978,7 @@ export {
   compileFencedSamples,
   customerProfileBundle,
   docsSyncBundle,
+  emptyCategoryBuckets,
   extractApiProcedure,
   extractDocReferences,
   extractFencedSamples,
@@ -32045,6 +31992,7 @@ export {
   meetingAnalysisBundle,
   orchestratorBundle,
   peopleProfileBundle,
+  persistAuditReport,
   pnpmBundle,
   prReviewBundle,
   projenBundle,
@@ -32084,10 +32032,6 @@ export {
   renderSourceTierExamples,
   renderUnblockDependentsScript,
   renderUnblockDependentsSection,
-  renderWorkflowDiagramsBundleHook,
-  renderWorkflowDiagramsCheckerScript,
-  renderWorkflowDiagramsRuleContent,
-  renderWorkflowDiagramsStarterPage,
   requirementsAnalystBundle,
   requirementsReviewerBundle,
   requirementsWriterBundle,
@@ -32110,7 +32054,7 @@ export {
   resolveTemplateVariables,
   resolveTypeScriptProjectOutdir,
   resolveUnblockDependents,
-  resolveWorkflowDiagrams,
+  runScan,
   slackBundle,
   softwareProfileBundle,
   standardsResearchBundle,
@@ -32128,7 +32072,6 @@ export {
   validateSkillEvalsConfig,
   validateStarlightSingleton,
   validateUnblockDependentsConfig,
-  validateWorkflowDiagramsConfig,
   vitestBundle
 };
 //# sourceMappingURL=index.mjs.map