@codedrifters/configulator 0.0.289 → 0.0.291

package/lib/index.mjs

@@ -585,13 +585,16 @@ var agendaAnalystSubAgent = {
     "   `duration_min` \xB1 5 minutes. If it doesn't, adjust section times",
     "   or cut content \u2014 do not ship a math-broken agenda.",
     "",
-    "7. **Create the folder `index.md` if missing.** Populate it with:",
+    "7. **Create the folder `index.md` if missing.** Populate it",
+    "   following the `stub-index-convention` rule:",
     "   - Frontmatter `title` (short sidebar label) and `description`",
     "     (one line).",
     "   - A 2\u20134 sentence summary of the meeting's objective and desired",
     "     outcomes pulled from the agenda.",
     "   - A `## Documents` section linking to `./agenda.md` (and",
     "     `./notes.md` once the meeting-analyst produces it).",
+    "   - No body `# Heading` \u2014 the frontmatter `title:` already",
+    "     renders as the page H1.",
     "",
     "   Do NOT set `sidebar.hidden: true` on `index.md` \u2014 it is the page",
     "   that should appear in the sidebar.",
@@ -1355,8 +1358,6 @@ function renderIssueTemplatesStarterPage(_it) {
     "description: Canonical gh issue create recipes \u2014 one per downstream phase label.",
     "---",
     "",
-    "# Issue Templates",
-    "",
     "This page lists the canonical `gh issue create` recipe for every",
     "downstream issue kind dispatched by an agent in this monorepo.",
     "Bundles and agent prompts cite the matching section below instead",
@@ -2791,6 +2792,71 @@ function assertValidProductContextPath(value) {
   }
 }
 
+// src/agent/bundles/stub-index-convention.ts
+function renderStubIndexConventionRuleContent() {
+  return [
+    "# Section Index Pages",
+    "",
+    "When any agent creates or updates an `index.md` (or `README.md`)",
+    "in a docs subdirectory under a Starlight content root, the file's",
+    "body must include:",
+    "",
+    "1. **A 1\u20132 paragraph summary** of the section's purpose and how",
+    "   it fits into the larger research, requirements, or capability",
+    "   area. Readers landing on the page should understand what's in",
+    "   the section without falling back to the sidebar.",
+    "",
+    "2. **A grouped, linked listing of the directory's children**",
+    "   (table or bullet list). When a natural taxonomy exists (e.g.",
+    "   organizations grouped by sub-segment, regulations grouped by",
+    "   jurisdiction, capabilities grouped by tier), use it. Otherwise",
+    "   sort alphabetically by title. Every listing entry must link",
+    "   to the child page.",
+    "",
+    "3. **No body `# Heading`.** Starlight renders the frontmatter",
+    "   `title:` as the page H1 automatically \u2014 a body H1 produces a",
+    "   duplicate. The same no-body-H1 contract that applies to skill",
+    "   templates and inline agent templates also applies to every",
+    "   index page emitted by an agent.",
+    "",
+    "## When this applies",
+    "",
+    "The convention applies to every `index.md` / `README.md` file",
+    "covered by the shared-index path globs documented in the",
+    "`shared-editing-safety` rule:",
+    "",
+    "- `docs/src/content/docs/**/index.md`",
+    "- `docs/src/content/docs/**/README.md`",
+    "",
+    "Any agent that scaffolds a new directory under a Starlight",
+    "content root MUST populate the directory's index page following",
+    "this contract \u2014 a one-sentence stub is not acceptable.",
+    "",
+    "## Reference shapes",
+    "",
+    "Existing rich indexes are the canonical reference shape. Examples:",
+    "",
+    "- A `<MEETINGS_ROOT>/<YYYY-MM-DD>-<slug>/index.md` populated by",
+    "  the `agenda-analyst` bundle: frontmatter `title` /",
+    "  `description`, a 2\u20134 sentence summary, and a `## Documents`",
+    "  section listing every page in the folder.",
+    "- A regulations scope index that opens with two paragraphs of",
+    "  context and groups every linked regulation under a",
+    "  `## Regulations` table by jurisdiction.",
+    "- A standards-organizations index that groups every linked",
+    "  organization under a `## Organizations` heading by role",
+    "  (governance, working group, implementer).",
+    "",
+    "## Out of scope",
+    "",
+    "- Auto-generated child listings via Astro/Starlight components.",
+    "  Agents emit hand-curated tables or bullet lists; the rule",
+    "  defines the shape, not the rendering technology.",
+    "- Backfilling pre-existing stub indexes is a downstream-consumer",
+    "  cleanup task, not a configulator change."
+  ].join("\n");
+}
+
 // src/agent/bundles/base.ts
 var createPackageSkill = {
   name: "create-package",
@@ -3876,6 +3942,16 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
         },
         tags: ["workflow"]
       },
+      {
+        name: "stub-index-convention",
+        description: "Section-index convention: every agent-emitted `index.md` / `README.md` under a Starlight docs root carries a contextual summary plus a grouped, linked listing of the directory's children \u2014 and no body `# Heading` (Starlight renders the frontmatter `title:` as the page H1).",
+        scope: AGENT_RULE_SCOPE.ALWAYS,
+        content: renderStubIndexConventionRuleContent(),
+        platforms: {
+          cursor: { exclude: true }
+        },
+        tags: ["workflow"]
+      },
       {
         name: "skill-evals",
         description: "Skill eval harness contract: declarative prompt/expected-output regression suites per skill at `<skillsRoot>/<skill-name>/evals/evals.json`, parameterised by a shared product-context fixture so the same eval shape works across every configulator-consuming project without forking fixtures.",
@@ -4151,8 +4227,6 @@ function buildBcmWriterSubAgent(paths) {
       "   tier: L1 | L2 | L3",
       "   ---",
       "",
-      "   # BCM Outline: <Capability Name>",
-      "",
       "   ## Capability Name",
       "   <noun or noun phrase \u2014 never a verb>",
       "",
@@ -4232,8 +4306,6 @@ function buildBcmWriterSubAgent(paths) {
       "   date: YYYY-MM-DD",
       "   ---",
       "",
-      "   # <Capability Name>",
-      "",
       "   ## Capability Definitions",
       "   <1\u20132 sentences from the outline's Proposed Definition, refined>",
       "",
@@ -4643,8 +4715,6 @@ title: "Business Model: <Segment Name>"
 description: "Business Model Canvas analysis for the <segment name> segment of the <industry> industry."
 ---
 
-# Business Model: <Segment Name>
-
 | Field | Value |
 |-------|-------|
 | **Industry** | <industry name> |
@@ -5028,8 +5098,6 @@ function buildBusinessModelsAnalystSubAgent(paths) {
       "   status: complete",
       "   ---",
       "",
-      "   # Business Model Scan: <Industry Name>",
-      "",
       "   ## Source Inputs",
       "   - Industry plan: <relative path>",
       "   - Prior research: <relative path> (optional)",
@@ -5117,8 +5185,12 @@ function buildBusinessModelsAnalystSubAgent(paths) {
       "",
       "7. **Create the segment index** at",
       "   `<BUSINESS_MODELS_ROOT>/<industry>/segments/<SEGMENT_SLUG>/index.md`",
-      "   if it does not already exist. The index should carry a short",
-      "   description and link to `./business-model.md`.",
+      "   if it does not already exist. Follow the",
+      "   `stub-index-convention` rule: a 1\u20132 paragraph summary of the",
+      "   segment plus a linked listing of every page in the folder",
+      "   (`./business-model.md` and any value-stream / capability pages",
+      "   that land later). No body `# Heading` \u2014 the frontmatter",
+      "   `title:` already renders as the page H1.",
       "",
       "8. **Create one `business-models:complete` issue** with",
       "   `Depends on: #<canvas-issue>`. Its body references the path to",
@@ -5909,8 +5981,6 @@ function buildCompanyProfileAnalystSubAgent(paths) {
       "   parent_issue: <N>",
       "   ---",
       "",
-      "   # Research Notes: <company name>",
-      "",
       "   ## Framing",
       "   <why this company was requested and what to learn>",
       "",
@@ -5972,8 +6042,6 @@ function buildCompanyProfileAnalystSubAgent(paths) {
       "   referencedIn: []",
       "   ---",
       "",
-      "   # <company name>",
-      "",
       "   ## Summary",
       "   <2\u20134 sentence elevator description: what they do, who they sell to>",
       "",
@@ -6384,8 +6452,6 @@ function buildCompanyProfileAnalystSubAgent(paths) {
       "     - <relative path to profile 2>",
       "   ---",
       "",
-      "   # <segment name> Competitive Analysis",
-      "",
       "   ## Market Overview",
       "   <landscape summary \u2014 total players, market structure, trends",
       "    visible from the profiles>",
@@ -6948,8 +7014,6 @@ archetype: <ARCHETYPE_SLUG>
 segment: <SEGMENT_SLUG>
 ---
 
-# <Customer Archetype Name>
-
 | Field | Value |
 |-------|-------|
 | **Archetype** | <short noun phrase identifying the archetype> |
@@ -7315,8 +7379,6 @@ function buildCustomerProfileAnalystSubAgent(paths) {
       "   scope: <SCOPE_SLUG>",
       "   ---",
       "",
-      "   # Customer Discovery: <Scope>",
-      "",
       "   ## Scope Context",
       "   - **Scope:** <SCOPE_SLUG>",
       "   - **Sources scanned:** <counts by source type>",
@@ -7462,8 +7524,6 @@ function buildCustomerProfileAnalystSubAgent(paths) {
       "   archetype: <ARCHETYPE_SLUG>",
       "   ---",
       "",
-      "   # Competitors: <Archetype Name>",
-      "",
       "   ## Market Overview",
       "   <Brief overview of the competitive landscape this archetype",
       "   evaluates.>",
@@ -9370,8 +9430,6 @@ function buildIndustryDiscoveryAnalystSubAgent(paths) {
       "   candidate_count: <N>",
       "   ---",
       "",
-      "   # Industry Candidates: <scope>",
-      "",
       "   ## Scope",
       "   <verbatim scope statement from the issue>",
       "",
@@ -9432,8 +9490,6 @@ function buildIndustryDiscoveryAnalystSubAgent(paths) {
       "   threshold: <0.0\u20131.0>",
       "   ---",
       "",
-      "   # Industry Evaluation: <scope>",
-      "",
       "   ## Fit Rubric",
       "   <verbatim rubric table, including weights and threshold>",
       "",
@@ -9490,8 +9546,6 @@ function buildIndustryDiscoveryAnalystSubAgent(paths) {
       "   evaluation_source: <EVALUATIONS_DIR>/<DISCOVERY_SLUG>.evaluation.md",
       "   ---",
       "",
-      "   # Industry Plan: <scope>",
-      "",
       "   ## Cleared Verticals",
       "   | Vertical | Score | Downstream Issue |",
       "   |----------|-------|------------------|",
@@ -9944,8 +9998,6 @@ function buildMaintenanceAuditSubAgent(paths) {
       "   status: complete",
       "   ---",
       "",
-      "   # Maintenance Audit: <AUDIT_SLUG>",
-      "",
       "   ## Scope",
       "   - **Docs root:** `<DOCS_ROOT>`",
       "   - **Checks run:** <list of check categories>",
@@ -10067,8 +10119,6 @@ function buildMaintenanceAuditSubAgent(paths) {
       "   status: complete",
       "   ---",
       "",
-      "   # Maintenance Fix: <AUDIT_SLUG>",
-      "",
       "   ## Source Audit Report",
       "   <link to the Phase 1 audit report>",
       "",
@@ -10169,8 +10219,6 @@ function buildMaintenanceAuditSubAgent(paths) {
       "   status: complete",
       "   ---",
       "",
-      "   # Maintenance Verify: <AUDIT_SLUG>",
-      "",
       "   ## Source Reports",
       "   - Scan report: <link>",
       "   - Fix report: <link>",
@@ -11761,6 +11809,14 @@ var DEFAULT_SOURCES_THRESHOLDS = {
   smallMax: 2,
   mediumMax: 5
 };
+var DEFAULT_BUNDLE_OVERRIDES = {
+  "req:write": {
+    acceptanceCriteria: { smallMax: 3, mediumMax: 20 }
+  },
+  "bcm:scaffold": {
+    acceptanceCriteria: { smallMax: 3, mediumMax: 12 }
+  }
+};
 var DEFAULT_DECOMPOSITION_TEMPLATE = [
   "## Scope gate: issue is too large to dispatch",
   "",
@@ -11800,22 +11856,58 @@ function resolveScopeGate(config) {
     DEFAULT_SOURCES_THRESHOLDS,
     "sources"
   );
+  const bundleOverrides = resolveBundleOverrides(
+    config?.bundleOverrides,
+    DEFAULT_BUNDLE_OVERRIDES
+  );
   return {
     enabled: config?.enabled ?? true,
     acceptanceCriteria: ac,
     sources,
     autoFile: config?.autoFile ?? false,
-    decompositionTemplate: config?.decompositionTemplate ?? DEFAULT_DECOMPOSITION_TEMPLATE
+    decompositionTemplate: config?.decompositionTemplate ?? DEFAULT_DECOMPOSITION_TEMPLATE,
+    bundleOverrides
+  };
+}
+function resolveOverrideForLabels(gate, labels) {
+  const overrideKeys = Object.keys(gate.bundleOverrides);
+  if (overrideKeys.length === 0 || labels.length === 0) {
+    return {
+      acceptanceCriteria: gate.acceptanceCriteria,
+      sources: gate.sources
+    };
+  }
+  const sortedLabels = [...labels].sort((a, b) => a.localeCompare(b));
+  const matchedLabel = sortedLabels.find(
+    (label) => Object.prototype.hasOwnProperty.call(gate.bundleOverrides, label)
+  );
+  if (matchedLabel === void 0) {
+    return {
+      acceptanceCriteria: gate.acceptanceCriteria,
+      sources: gate.sources
+    };
+  }
+  const override = gate.bundleOverrides[matchedLabel];
+  return {
+    acceptanceCriteria: override.acceptanceCriteria ?? gate.acceptanceCriteria,
+    sources: override.sources ?? gate.sources,
+    matchedLabel
   };
 }
 function validateScopeGateConfig(config) {
   return resolveScopeGate(config);
 }
-function classifyIssueScope(body, gate) {
+function classifyIssueScope(body, gate, labels = []) {
   const acCount = countAcceptanceCriteria(body);
   const sourcesCount = countSources(body);
-  const scope = resolveScopeClass(acCount, sourcesCount, gate);
-  return { scope, acCount, sourcesCount };
+  const effective = resolveOverrideForLabels(gate, labels);
+  const scope = resolveScopeClass(acCount, sourcesCount, effective);
+  return {
+    scope,
+    acCount,
+    sourcesCount,
+    matchedLabel: effective.matchedLabel
+  };
 }
 function renderScopeGateSection(gate) {
   const { acceptanceCriteria: ac, sources } = gate;
@@ -11891,6 +11983,38 @@ function renderScopeGateSection(gate) {
       "   is in place."
     );
   }
+  const overrideEntries = Object.entries(gate.bundleOverrides);
+  if (overrideEntries.length > 0) {
+    lines.push(
+      "",
+      "### Per-phase-label thresholds",
+      "",
+      "Issues whose `type:*` or phase label matches an entry below are",
+      "classified against the override's thresholds instead of the",
+      "global `acceptance-criteria` / `sources` defaults. This",
+      "accommodates **content-spec workflows** \u2014 issues whose AC list",
+      "is the per-section content checklist for one cohesive document,",
+      "not a phase-completion checklist that can be decomposed.",
+      "",
+      "| Phase label | AC `mediumMax` | Sources `mediumMax` |",
+      "|-------------|----------------|---------------------|"
+    );
+    const sortedKeys = overrideEntries.map(([k]) => k).sort();
+    for (const label of sortedKeys) {
+      const override = gate.bundleOverrides[label];
+      const acMax = override.acceptanceCriteria?.mediumMax;
+      const sourcesMax = override.sources?.mediumMax;
+      const acCell = acMax === void 0 ? "_(global)_" : `${acMax}`;
+      const sourcesCell = sourcesMax === void 0 ? "_(global)_" : `${sourcesMax}`;
+      lines.push(`| \`${label}\` | ${acCell} | ${sourcesCell} |`);
+    }
+    lines.push(
+      "",
+      "When an issue carries multiple labels that each match an entry",
+      "in this table, the orchestrator picks the **first match in",
+      "alphabetical order on the label name** \u2014 first-wins, deterministic."
+    );
+  }
   lines.push(
     "",
     "### Decomposition-proposal template",
@@ -11907,12 +12031,21 @@ function renderScopeGateSection(gate) {
 }
 function renderScopeGateShellHelpers(gate) {
   const { acceptanceCriteria: ac, sources } = gate;
-  return [
+  const lines = [
     "# Classify an issue body against the scope-gate thresholds.",
     "# Reads the issue body from stdin. Echoes one of 'small',",
     "# 'medium', or 'large' on stdout. Writes the observed counts to",
     "# stderr as `ac=<n> sources=<n>` so the caller can embed them in",
     "# the decomposition-proposal comment.",
+    "#",
+    "# Effective per-issue thresholds are read from the four",
+    "# `_EFFECTIVE_*` shell variables. The caller is expected to set",
+    "# them via `bundle_override_for()` before invoking scope_of();",
+    "# defaults preserve the global thresholds.",
+    `_EFFECTIVE_AC_SMALL_MAX="\${_EFFECTIVE_AC_SMALL_MAX:-${ac.smallMax}}"`,
+    `_EFFECTIVE_AC_MEDIUM_MAX="\${_EFFECTIVE_AC_MEDIUM_MAX:-${ac.mediumMax}}"`,
+    `_EFFECTIVE_SOURCES_SMALL_MAX="\${_EFFECTIVE_SOURCES_SMALL_MAX:-${sources.smallMax}}"`,
+    `_EFFECTIVE_SOURCES_MEDIUM_MAX="\${_EFFECTIVE_SOURCES_MEDIUM_MAX:-${sources.mediumMax}}"`,
     "scope_of() {",
     "  local body",
     "  body=$(cat)",
@@ -11941,15 +12074,79 @@ function renderScopeGateShellHelpers(gate) {
     "    END { print count }",
     "  ')",
     `  printf 'ac=%s sources=%s\\n' "$ac_count" "$sources_count" >&2`,
-    `  if [ "$ac_count" -le ${ac.smallMax} ] && [ "$sources_count" -le ${sources.smallMax} ]; then`,
+    '  if [ "$ac_count" -le "$_EFFECTIVE_AC_SMALL_MAX" ] && [ "$sources_count" -le "$_EFFECTIVE_SOURCES_SMALL_MAX" ]; then',
     "    echo small",
-    `  elif [ "$ac_count" -le ${ac.mediumMax} ] && [ "$sources_count" -le ${sources.mediumMax} ]; then`,
+    '  elif [ "$ac_count" -le "$_EFFECTIVE_AC_MEDIUM_MAX" ] && [ "$sources_count" -le "$_EFFECTIVE_SOURCES_MEDIUM_MAX" ]; then',
     "    echo medium",
     "  else",
     "    echo large",
     "  fi",
+    "}",
+    "",
+    "# Resolve per-phase-label threshold overrides. Reads a newline-",
+    "# separated list of label names on stdin and echoes effective",
+    "# threshold variable assignments (one per line) on stdout. The",
+    "# caller `eval`s the output to set the four `_EFFECTIVE_*`",
+    "# variables before calling `scope_of()`. Also echoes",
+    "# `MATCHED_LABEL=<label>` (or `MATCHED_LABEL=`) so the caller can",
+    "# report which override fired.",
+    "#",
+    "# Tie-breaking: when more than one label matches an override key,",
+    "# the alphabetical first-wins rule applies \u2014 the same rule the",
+    "# TypeScript classifier uses.",
+    "bundle_override_for() {",
+    `  local default_ac_small=${ac.smallMax}`,
+    `  local default_ac_medium=${ac.mediumMax}`,
+    `  local default_sources_small=${sources.smallMax}`,
+    `  local default_sources_medium=${sources.mediumMax}`,
+    "  # Sort labels alphabetically so the first match is deterministic.",
+    "  local sorted_labels",
+    "  sorted_labels=$(LC_ALL=C sort)",
+    "  local matched_label=''",
+    "  local ac_small=$default_ac_small",
+    "  local ac_medium=$default_ac_medium",
+    "  local sources_small=$default_sources_small",
+    "  local sources_medium=$default_sources_medium",
+    "  while IFS= read -r label; do",
+    '    [ -z "$label" ] && continue',
+    `    case "$label" in`
+  ];
+  const sortedKeys = Object.keys(gate.bundleOverrides).sort();
+  if (sortedKeys.length === 0) {
+    lines.push("      *) ;;");
+  } else {
+    for (const label of sortedKeys) {
+      const override = gate.bundleOverrides[label];
+      const acThresholds = override.acceptanceCriteria;
+      const sourcesThresholds = override.sources;
+      const branchLines = [`      '${label}')`];
+      if (acThresholds !== void 0) {
+        branchLines.push(`        ac_small=${acThresholds.smallMax}`);
+        branchLines.push(`        ac_medium=${acThresholds.mediumMax}`);
+      }
+      if (sourcesThresholds !== void 0) {
+        branchLines.push(`        sources_small=${sourcesThresholds.smallMax}`);
+        branchLines.push(
+          `        sources_medium=${sourcesThresholds.mediumMax}`
+        );
+      }
+      branchLines.push(`        matched_label='${label}'`);
+      branchLines.push("        break");
+      branchLines.push("        ;;");
+      lines.push(...branchLines);
+    }
+  }
+  lines.push(
+    "    esac",
+    `  done <<<"$sorted_labels"`,
+    `  printf 'MATCHED_LABEL=%s\\n' "$matched_label"`,
+    `  printf '_EFFECTIVE_AC_SMALL_MAX=%s\\n' "$ac_small"`,
+    `  printf '_EFFECTIVE_AC_MEDIUM_MAX=%s\\n' "$ac_medium"`,
+    `  printf '_EFFECTIVE_SOURCES_SMALL_MAX=%s\\n' "$sources_small"`,
+    `  printf '_EFFECTIVE_SOURCES_MEDIUM_MAX=%s\\n' "$sources_medium"`,
     "}"
-  ].join("\n");
+  );
+  return lines.join("\n");
 }
 function resolveThresholds(supplied, defaults, field) {
   const merged = {
@@ -11959,6 +12156,42 @@ function resolveThresholds(supplied, defaults, field) {
   assertValidThresholds(merged, field);
   return merged;
 }
+function resolveBundleOverrides(supplied, defaults) {
+  const out = {};
+  for (const [label, override] of Object.entries(defaults)) {
+    out[label] = override;
+  }
+  if (supplied !== void 0) {
+    for (const label of Object.keys(supplied)) {
+      const value = supplied[label];
+      if (value === void 0) {
+        delete out[label];
+        continue;
+      }
+      const resolved = {};
+      if (value.acceptanceCriteria !== void 0) {
+        resolved.acceptanceCriteria = resolveThresholds(
+          value.acceptanceCriteria,
+          DEFAULT_AC_THRESHOLDS,
+          "acceptanceCriteria"
+        );
+      }
+      if (value.sources !== void 0) {
+        resolved.sources = resolveThresholds(
+          value.sources,
+          DEFAULT_SOURCES_THRESHOLDS,
+          "sources"
+        );
+      }
+      if (resolved.acceptanceCriteria === void 0 && resolved.sources === void 0) {
+        delete out[label];
+        continue;
+      }
+      out[label] = resolved;
+    }
+  }
+  return out;
+}
 function assertValidThresholds(thresholds, field) {
   const { smallMax, mediumMax } = thresholds;
   for (const [key, value] of [
@@ -11982,8 +12215,8 @@ function assertValidThresholds(thresholds, field) {
     );
   }
 }
-function resolveScopeClass(acCount, sourcesCount, gate) {
-  const { acceptanceCriteria: ac, sources } = gate;
+function resolveScopeClass(acCount, sourcesCount, thresholds) {
+  const { acceptanceCriteria: ac, sources } = thresholds;
   if (acCount <= ac.smallMax && sourcesCount <= sources.smallMax) {
     return "small";
   }
@@ -12563,7 +12796,9 @@ function buildCheckBlockedScript(tiers, scopeGate, runRatio) {
     "STALE_BLOCKED_HOURS=168",
     `SCOPE_GATE_ENABLED=${scopeGate.enabled ? "1" : "0"}`,
     `SCOPE_GATE_AUTO_FILE=${scopeGate.autoFile ? "1" : "0"}`,
+    `SCOPE_AC_SMALL_MAX=${scopeGate.acceptanceCriteria.smallMax}`,
     `SCOPE_AC_MEDIUM_MAX=${scopeGate.acceptanceCriteria.mediumMax}`,
+    `SCOPE_SOURCES_SMALL_MAX=${scopeGate.sources.smallMax}`,
     `SCOPE_SOURCES_MEDIUM_MAX=${scopeGate.sources.mediumMax}`,
     `RUN_RATIO_ENABLED=${runRatio.enabled ? "1" : "0"}`,
     `RUN_RATIO_DISPATCH_PER_HOUSEKEEPING=${runRatio.ratio}`,
@@ -12917,12 +13152,45 @@ function buildCheckBlockedScript(tiers, scopeGate, runRatio) {
     '    echo "SCOPE #${issue_num} disabled"',
     "    return 0",
     "  fi",
+    "  # Fetch the body and labels in a single API call so we resolve",
+    "  # any per-phase-label override against the issue's actual labels.",
+    "  local issue_json",
+    '  issue_json=$(gh issue view "$issue_num" --json body,labels 2>/dev/null || echo "")',
+    '  if [[ -z "$issue_json" ]]; then',
+    '    echo "SCOPE #${issue_num} unknown \u2014 could not read issue body"',
+    "    return 1",
+    "  fi",
     "  local body",
-    `  body=$(gh issue view "$issue_num" --json body --jq '.body' 2>/dev/null || echo "")`,
+    `  body=$(printf '%s' "$issue_json" | jq -r '.body // ""')`,
     '  if [[ -z "$body" ]]; then',
     '    echo "SCOPE #${issue_num} unknown \u2014 could not read issue body"',
     "    return 1",
     "  fi",
+    "  local labels",
+    `  labels=$(printf '%s' "$issue_json" | jq -r '.labels[]?.name // empty')`,
+    "  # Resolve the effective thresholds. `bundle_override_for` reads",
+    "  # labels on stdin and emits `KEY=VALUE` assignments (one per line)",
+    "  # for the four `_EFFECTIVE_*` variables plus `MATCHED_LABEL`.",
+    "  local override_output",
+    `  override_output=$(printf '%s\\n' "$labels" | bundle_override_for)`,
+    "  local matched_label=''",
+    "  local _EFFECTIVE_AC_SMALL_MAX=$SCOPE_AC_SMALL_MAX",
+    "  local _EFFECTIVE_AC_MEDIUM_MAX=$SCOPE_AC_MEDIUM_MAX",
+    "  local _EFFECTIVE_SOURCES_SMALL_MAX=$SCOPE_SOURCES_SMALL_MAX",
+    "  local _EFFECTIVE_SOURCES_MEDIUM_MAX=$SCOPE_SOURCES_MEDIUM_MAX",
+    "  while IFS= read -r assignment; do",
+    '    [ -z "$assignment" ] && continue',
+    '    case "$assignment" in',
+    "      MATCHED_LABEL=*) matched_label=${assignment#MATCHED_LABEL=} ;;",
+    "      _EFFECTIVE_AC_SMALL_MAX=*) _EFFECTIVE_AC_SMALL_MAX=${assignment#_EFFECTIVE_AC_SMALL_MAX=} ;;",
+    "      _EFFECTIVE_AC_MEDIUM_MAX=*) _EFFECTIVE_AC_MEDIUM_MAX=${assignment#_EFFECTIVE_AC_MEDIUM_MAX=} ;;",
+    "      _EFFECTIVE_SOURCES_SMALL_MAX=*) _EFFECTIVE_SOURCES_SMALL_MAX=${assignment#_EFFECTIVE_SOURCES_SMALL_MAX=} ;;",
+    "      _EFFECTIVE_SOURCES_MEDIUM_MAX=*) _EFFECTIVE_SOURCES_MEDIUM_MAX=${assignment#_EFFECTIVE_SOURCES_MEDIUM_MAX=} ;;",
+    "    esac",
+    '  done <<<"$override_output"',
+    "  # Export the effective thresholds so scope_of() picks them up.",
+    "  export _EFFECTIVE_AC_SMALL_MAX _EFFECTIVE_AC_MEDIUM_MAX",
+    "  export _EFFECTIVE_SOURCES_SMALL_MAX _EFFECTIVE_SOURCES_MEDIUM_MAX",
     "  local scope counts",
     "  # scope_of writes counts to stderr (ac=N sources=N); capture both.",
     `  scope=$(printf '%s' "$body" | scope_of 2> >(read -r counts; echo "$counts" >&2))`,
@@ -12936,9 +13204,17 @@ function buildCheckBlockedScript(tiers, scopeGate, runRatio) {
     `  sources_count=$(echo "$stderr_capture" | grep -oE 'sources=[0-9]+' | head -1 | cut -d= -f2)`,
     "  ac_count=${ac_count:-0}",
     "  sources_count=${sources_count:-0}",
-    "  printf 'SCOPE #%s %s ac=%s sources=%s ac_limit=%s sources_limit=%s auto_file=%s\\n' \\",
-    '    "$issue_num" "$scope" "$ac_count" "$sources_count" \\',
-    '    "$SCOPE_AC_MEDIUM_MAX" "$SCOPE_SOURCES_MEDIUM_MAX" "$SCOPE_GATE_AUTO_FILE"',
+    '  if [ -n "$matched_label" ]; then',
+    "    printf 'SCOPE #%s %s ac=%s sources=%s ac_limit=%s sources_limit=%s auto_file=%s matched_label=%s\\n' \\",
+    '      "$issue_num" "$scope" "$ac_count" "$sources_count" \\',
+    '      "$_EFFECTIVE_AC_MEDIUM_MAX" "$_EFFECTIVE_SOURCES_MEDIUM_MAX" \\',
+    '      "$SCOPE_GATE_AUTO_FILE" "$matched_label"',
+    "  else",
+    "    printf 'SCOPE #%s %s ac=%s sources=%s ac_limit=%s sources_limit=%s auto_file=%s\\n' \\",
+    '      "$issue_num" "$scope" "$ac_count" "$sources_count" \\',
+    '      "$_EFFECTIVE_AC_MEDIUM_MAX" "$_EFFECTIVE_SOURCES_MEDIUM_MAX" \\',
+    '      "$SCOPE_GATE_AUTO_FILE"',
+    "  fi",
     "}",
     "",
     "cmd_tick() {",
@@ -13143,9 +13419,16 @@ var orchestratorSubAgent = {
     "The output is one line of the form:",
     "",
     "```",
-    "SCOPE #<n> <small|medium|large> ac=<n> sources=<n> ac_limit=<n> sources_limit=<n> auto_file=<0|1>",
+    "SCOPE #<n> <small|medium|large> ac=<n> sources=<n> ac_limit=<n> sources_limit=<n> auto_file=<0|1> [matched_label=<label>]",
     "```",
     "",
+    "When `matched_label=<label>` is present, the scope gate applied a",
+    "per-phase-label override (e.g. `req:write` raises the AC ceiling to",
+    "20 for content-spec workflows whose AC list is the per-section",
+    "checklist for one document). The `ac_limit` / `sources_limit`",
+    "values reflect the override; the global thresholds are documented",
+    "in the **Scope gate** section in `CLAUDE.md`.",
+    "",
     "If the scope is `small` or `medium`, continue \u2014 the issue is",
     "dispatchable. Record the first `PICK` line as the next work item",
     "and proceed to Phase G:",
@@ -14102,8 +14385,6 @@ function buildPeopleProfileAnalystSubAgent(paths) {
       "   parent_issue: <N>",
       "   ---",
       "",
-      "   # Research Notes: <person name>",
-      "",
       "   ## Framing",
       "   <why this person was requested and what to learn>",
       "",
@@ -14165,8 +14446,6 @@ function buildPeopleProfileAnalystSubAgent(paths) {
       "   notes: <NOTES_DIR>/<PERSON_SLUG>.notes.md",
       "   ---",
       "",
-      "   # <person name>",
-      "",
       "   ## Summary",
       "   <2\u20134 sentence elevator description: who they are, what they do,",
       "   why they matter to this project>",
@@ -16750,8 +17029,6 @@ jurisdiction: <federal | state | provincial | international | local>
 industry: <industry-slug or 'platform'>
 ---
 
-# <Regulation Name>
-
 | Field | Value |
 |-------|-------|
 | **Official name** | <full legal name> |
@@ -17122,8 +17399,6 @@ function buildRegulatoryResearchAnalystSubAgent(paths) {
       "   scope: <SCOPE_SLUG>",
       "   ---",
       "",
-      "   # Regulatory Scan: <Scope>",
-      "",
       "   ## Scope Context",
       "   - **Scope type:** <industry / jurisdiction / platform>",
       "   - **Scope identifier:** <SCOPE_SLUG>",
@@ -17174,7 +17449,12 @@ function buildRegulatoryResearchAnalystSubAgent(paths) {
       "",
       "7. **Create or update the scope index page** at",
       "   `<SCOPE_INDEX_PAGE>` so downstream regulations link back to a",
-      "   coherent landing page for the scope.",
+      "   coherent landing page for the scope. Follow the",
+      "   `stub-index-convention` rule: the body must carry a 1\u20132",
+      "   paragraph contextual summary plus a grouped, linked listing of",
+      "   every regulation in the scope (e.g. by jurisdiction). No body",
+      "   `# Heading` \u2014 the frontmatter `title:` already renders as the",
+      "   page H1.",
       "",
       "8. **Commit and push** the scan report and the scope index page.",
       "   Close the scan issue.",
@@ -18032,8 +18312,6 @@ function buildRequirementsAnalystSubAgent(paths) {
       "   status: complete",
       "   ---",
       "",
-      "   # Requirements Scan: <scope>",
-      "",
       "   ## Source Documents Reviewed",
       "   - <path> \u2014 <brief description>",
       "",
@@ -18169,42 +18447,32 @@ function buildRequirementsAnalystSubAgent(paths) {
       "   directory under `<REQUIREMENTS_ROOT>/<category>/` to find the next",
       "   available `NNN` for each proposed requirement.",
       "",
-      "5. **Create requirement issues.** For each proposal:",
+      "5. **Create requirement issues.** For each proposal, file a",
+      "   `req:write` issue using the canonical recipe documented in",
+      "   `## Template: req:write` of",
+      "   `docs/src/content/docs/agents/issue-templates.md`.",
       "",
       "   All `type:requirement` issues default to `priority:medium` (override",
       "   only if the proposal's priority was explicitly High or Low). Each",
       "   issue must also carry the `req:write` phase label plus the matching",
       "   `tier:*` label so the downstream `requirements-writer` bundle picks",
-      "   it up with the correct tier.",
-      "",
-      "   ```bash",
-      "   gh issue create \\",
-      '     --title "docs(<category>): <PREFIX>-<NNN> \u2014 <title>" \\',
-      '     --label "type:requirement" --label "req:write" --label "tier:<tier-slug>" --label "status:ready" --label "priority:medium" \\',
-      '     --body "## Objective',
-      "   Write <PREFIX>-<NNN> \u2014 <title>.",
-      "",
-      "   **Category:** <BR/FR/NFR/TR/ADR/SEC/DR/INT/OPS/UX/MT>",
-      "   **Tier:** <platform/industry/customer-workflow/consumer-app>",
-      "   **Output Path:** <REQUIREMENTS_ROOT>/<category-dir>/<PREFIX>-<NNN>-<slug>.md",
-      "",
-      "   ## Context",
-      "   - **Gap identified by:** requirements scan of <source>",
-      "   - **Proposals file:** <RESEARCH_REQUIREMENTS_ROOT>/req-proposals-<scope>-<date>.md",
+      "   it up with the correct tier. Concretely, the label list includes",
+      '   `--label "type:requirement"`, `--label "req:write"`,',
+      '   `--label "tier:<tier-slug>"`, `--label "status:ready"`, and',
+      '   `--label "priority:medium"`.',
       "",
-      "   ## Inputs / Read",
-      "   - **Depends on:** (none)",
-      "   - **Read:** <RESEARCH_REQUIREMENTS_ROOT>/req-proposals-<scope>-<date>.md, <source docs>",
+      "   The body must carry the three writer-required fields in an",
+      "   `## Objective` block, written as bold-prefixed lines so the",
+      "   writer's intake parser can pull them out:",
       "",
-      "   ## Acceptance Criteria",
-      "   - [ ] Requirement document follows <category> template",
-      "   - [ ] Traceability links to source BCM/competitive/product doc",
-      "   - [ ] Registry index updated",
-      "   - [ ] Decision authority rules followed (direct write vs. proposed)",
+      "   - `**Category:** <BR/FR/NFR/TR/ADR/SEC/DR/INT/OPS/UX/MT>`",
+      "   - `**Tier:** <platform/industry/customer-workflow/consumer-app>`",
+      "   - `**Output Path:** <REQUIREMENTS_ROOT>/<category-dir>/<PREFIX>-<NNN>-<slug>.md`",
       "",
-      "   ## Scope Size",
-      '   small"',
-      "   ```",
+      "   Then under `## Inputs / Read`, list the proposals file",
+      "   (`<RESEARCH_REQUIREMENTS_ROOT>/req-proposals-<scope>-<date>.md`)",
+      "   and any source documents the writer should consult (BCM model",
+      "   docs, competitive analyses, product docs).",
       "",
       "   When one of Category / Tier / Output Path could not be derived",
       "   from the proposal (for example, the proposal omitted the Tier",
@@ -18380,8 +18648,6 @@ var TEMPLATE_BR = `---
 title: "BR-NNN: [Business Requirement Title]"
 ---
 
-# BR-NNN: [Business Requirement Title]
-
 ## Metadata
 
 | Field | Value |
@@ -18489,8 +18755,6 @@ var TEMPLATE_FR = `---
 title: "FR-NNN: [Functional Requirement Title]"
 ---
 
-# FR-NNN: [Functional Requirement Title]
-
 ## Metadata
 
 | Field | Value |
@@ -18630,8 +18894,6 @@ var TEMPLATE_NFR = `---
 title: "NFR-NNN: [Non-Functional Requirement Title]"
 ---
 
-# NFR-NNN: [Non-Functional Requirement Title]
-
 ## Metadata
 
 | Field | Value |
@@ -18732,8 +18994,6 @@ var TEMPLATE_TR = `---
 title: "TR-NNN: [Technical Requirement Title]"
 ---
 
-# TR-NNN: [Technical Requirement Title]
-
 ## Metadata
 
 | Field | Value |
@@ -18885,8 +19145,6 @@ var TEMPLATE_ADR = `---
 title: "ADR-NNN: [Decision Title]"
 ---
 
-# ADR-NNN: [Decision Title]
-
 ## Metadata
 
 | Field | Value |
@@ -19015,8 +19273,6 @@ var TEMPLATE_SEC = `---
 title: "SEC-NNN: [Security Requirement Title]"
 ---
 
-# SEC-NNN: [Security Requirement Title]
-
 ## Metadata
 
 | Field | Value |
@@ -19128,8 +19384,6 @@ var TEMPLATE_DR = `---
 title: "DR-NNN: [Data Requirement Title]"
 ---
 
-# DR-NNN: [Data Requirement Title]
-
 ## Metadata
 
 | Field | Value |
@@ -19244,8 +19498,6 @@ var TEMPLATE_INT = `---
 title: "INT-NNN: [Integration Requirement Title]"
 ---
 
-# INT-NNN: [Integration Requirement Title]
-
 ## Metadata
 
 | Field | Value |
@@ -19377,8 +19629,6 @@ var TEMPLATE_OPS = `---
 title: "OPS-NNN: [Operational Requirement Title]"
 ---
 
-# OPS-NNN: [Operational Requirement Title]
-
 ## Metadata
 
 | Field | Value |
@@ -19493,8 +19743,6 @@ var TEMPLATE_UX = `---
 title: "UX-NNN: [UX Requirement Title]"
 ---
 
-# UX-NNN: [UX Requirement Title]
-
 ## Metadata
 
 | Field | Value |
@@ -19611,8 +19859,6 @@ var TEMPLATE_MT = `---
 title: "MT-NNN: [Multi-Tenancy Requirement Title]"
 ---
 
-# MT-NNN: [Multi-Tenancy Requirement Title]
-
 ## Metadata
 
 | Field | Value |
@@ -19765,8 +20011,6 @@ var TEMPLATE_REQUIREMENTS_README = `---
 title: "[Project Name] \u2014 Requirements Documentation"
 ---
 
-# [Project Name] \u2014 Requirements Documentation
-
 This directory contains the structured requirements taxonomy for [Project Name]. It covers the full lifecycle from business intent through operational concerns, providing traceability between strategic goals and implementation work.
 
 ## Taxonomy Overview
@@ -20523,12 +20767,9 @@ function buildRequirementsWriterSubAgent(paths) {
       "tier: platform",
       "---",
       "",
-      "# FR-001: User Registration",
-      "",
       "...",
       "```",
       "",
-      "The `title` value must match the document's `# Heading` line.",
       "Titles containing colons must be wrapped in double quotes. The",
       "`tier` field must be one of `platform`, `industry`,",
       "`customer-workflow`, or `consumer-app` (use whatever tier slugs the",
@@ -22592,8 +22833,6 @@ function buildResearchAnalystSubAgent(paths) {
       "   slice_count: <N>",
       "   ---",
       "",
-      "   # Research Scope: <question>",
-      "",
       "   ## Question",
       "   <verbatim question from the issue>",
       "",
@@ -22663,8 +22902,6 @@ function buildResearchAnalystSubAgent(paths) {
       "   parent_issue: <N>",
       "   ---",
       "",
-      "   # Slice NN: <title>",
-      "",
       "   ## Question",
       "   <the slice-level question>",
       "",
@@ -22729,8 +22966,6 @@ function buildResearchAnalystSubAgent(paths) {
       "   slices_read: <count>",
       "   ---",
       "",
-      "   # Verification Report: <question>",
-      "",
       "   ## Acceptance Criteria Coverage",
       "   - [x] <criterion> \u2014 covered by slice(s) <NN, NN>",
       "   - [ ] <criterion> \u2014 **not covered**; gap noted in deliverable",
@@ -23338,8 +23573,6 @@ function buildSoftwareProfileAnalystSubAgent(paths) {
       "   parent_issue: <N>",
       "   ---",
       "",
-      "   # Research Notes: <product name>",
-      "",
       "   ## Framing",
       "   <why this product was requested and what to learn>",
       "",
@@ -23400,8 +23633,6 @@ function buildSoftwareProfileAnalystSubAgent(paths) {
       "   notes: <NOTES_DIR>/<PRODUCT_SLUG>.notes.md",
       "   ---",
       "",
-      "   # <product name>",
-      "",
       "   ## Summary",
       "   <2\u20134 sentence elevator description: what it does, who it's for>",
       "",
@@ -23486,8 +23717,6 @@ function buildSoftwareProfileAnalystSubAgent(paths) {
       "updated: YYYY-MM-DD",
       "---",
       "",
-      "# Software Feature Matrix",
-      "",
       "| product | feature | <segment-1> | <segment-2> | ... | score | source |",
       "|---------|---------|-------------|-------------|-----|-------|--------|",
       "| <slug>  | <feature-name> | 0\u20131 | 0\u20131 | ... | <weighted-sum> | <profile-path> |",
@@ -24115,8 +24344,6 @@ title: "<Standard Name>"
 description: "Overview and cross-version comparison of <Standard Name>."
 ---
 
-# <Standard Name>
-
 | Field | Value |
 |-------|-------|
 | **Standard** | <standard name> |
@@ -24434,8 +24661,6 @@ function buildStandardsResearchAnalystSubAgent(paths) {
       "   standard: <STANDARD_SLUG>",
       "   ---",
       "",
-      "   # Query Plan: <Standard Name>",
-      "",
       "   ## Context",
       "   <1\u20132 paragraphs on why this standard matters to the consuming",
       "   project and what gaps this research campaign fills.>",
@@ -24637,7 +24862,14 @@ function buildStandardsResearchAnalystSubAgent(paths) {
       "   the overview page, then populate each section from the version",
       "   pages.",
       "",
-      "4. **Write the overview page** at `<OVERVIEW_PAGE>`. Fill:",
+      "4. **Write the overview page** at `<OVERVIEW_PAGE>`. Follow",
+      "   the `stub-index-convention` rule: the body opens with a",
+      "   1\u20132 paragraph contextual summary of the standard and its",
+      "   versions, and the version pages, modules, and extensions",
+      "   sections below double as the grouped, linked listing of",
+      "   every child page in the standard's folder. No body",
+      "   `# Heading` \u2014 the frontmatter `title:` already renders as",
+      "   the page H1. Required sections to fill:",
       "   - **Version Timeline** \u2014 publication dates, status, milestones",
       "   - **Module / Resource Maturity Progression** \u2014 matrix with",
       "     modules as rows and versions as columns, using the standard's",
@@ -32438,6 +32670,7 @@ export {
   DEFAULT_API_EXTRACTOR_REPORT_FILENAME,
   DEFAULT_API_EXTRACTOR_REPORT_FOLDER,
   DEFAULT_AUDIT_REPORT_DIR,
+  DEFAULT_BUNDLE_OVERRIDES,
   DEFAULT_DECOMPOSITION_TEMPLATE,
   DEFAULT_DISPATCH_MODEL,
   DEFAULT_DISPATCH_TO_HOUSEKEEPING_RATIO,
@@ -32609,6 +32842,7 @@ export {
   renderSkillEvalsRuleContent,
   renderSkillEvalsRunnerScript,
   renderSourceTierExamples,
+  renderStubIndexConventionRuleContent,
   renderUnblockDependentsScript,
   renderUnblockDependentsSection,
   requirementsAnalystBundle,
@@ -32623,6 +32857,7 @@ export {
   resolveModelAlias,
   resolveOrchestratorAssets,
   resolveOutdirFromPackageName,
+  resolveOverrideForLabels,
   resolveProgressFiles,
   resolveRunRatio,
   resolveScheduledTasks,