@codedrifters/configulator 0.0.329 → 0.0.330

package/lib/index.mjs

@@ -586,7 +586,8 @@ var agendaAnalystSubAgent = {
     "   or cut content \u2014 do not ship a math-broken agenda.",
     "",
     "7. **Create the folder `index.md` if missing.** Populate it",
-    "   following the `stub-index-convention` rule:",
+    "   following the section-index-page contract in the",
+    "   `shared-editing-safety` rule:",
     "   - Frontmatter `title` (short sidebar label) and `description`",
     "     (one line).",
     "   - A 2\u20134 sentence summary of the meeting's objective and desired",
@@ -1159,11 +1160,7 @@ var awsCdkBundle = {
 // src/agent/bundles/issue-templates.ts
 var DEFAULT_ISSUE_TEMPLATES_ENABLED = true;
 var DEFAULT_ISSUE_TEMPLATES_PATH = "docs/src/content/docs/agents/issue-templates.md";
-var DEFAULT_ISSUE_TEMPLATES_BUNDLE_PATH_PATTERNS = [
-  "packages/@codedrifters/configulator/src/agent/bundles/**/*.ts",
-  ".claude/agents/**/*.md",
-  ".claude/skills/**/*.md"
-];
+var DEFAULT_ISSUE_TEMPLATES_BUNDLE_PATH_PATTERNS = [".claude/agents/**/*.md", ".claude/skills/**/*.md"];
 var DEFAULT_ISSUE_TEMPLATES_EMIT_CHECKER = false;
 var DEFAULT_ISSUE_TEMPLATES_EMIT_STARTER = false;
 var DEFAULT_ISSUE_TEMPLATES_REQUIRE_REFERENCE = true;
@@ -2332,7 +2329,66 @@ function renderSharedEditingRuleContent(se) {
     "conflicts; rewriting or reordering existing rows almost always",
     "does. If a shared index needs a structural change (column",
     "added, sort key changed), file a dedicated issue for the change",
-    "rather than bundling it into a content-contributing PR."
+    "rather than bundling it into a content-contributing PR.",
+    "",
+    "## Section Index Page Shape",
+    "",
+    "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 listed above:",
+    "",
+    "- `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."
   );
   return lines.join("\n");
 }
@@ -2887,71 +2943,6 @@ 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/temporal-framing.ts
 var DEFAULT_TEMPORAL_FRAMING_ENABLED = true;
 var DEFAULT_TEMPORAL_FRAMING_PATHS = [
@@ -4120,6 +4111,12 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "issue-label-conventions",
         description: "Priority and status label taxonomy, defaults, inference rules, and blocking rules for agent-created or updated issues",
+        // ALWAYS scope: every agent (and the user) needs the label
+        // taxonomy whenever an issue gets created or updated, which
+        // happens from any context — not only when editing agent /
+        // skill / bundle source. Consumers that want to narrow the
+        // load can override via `agentConfig.additionalRulePaths`
+        // or `excludeRules`.
         scope: AGENT_RULE_SCOPE.ALWAYS,
         content: [
           "# Issue Label Conventions",
@@ -4485,7 +4482,13 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "progress-file-convention",
         description: "Progress-file schema and write rules, partial-resume protocol, stale-branch decision tree, and [BLOCKED] comment format that let phased agents survive crashes without losing work.",
-        scope: AGENT_RULE_SCOPE.ALWAYS,
+        scope: AGENT_RULE_SCOPE.FILE_PATTERN,
+        // Bundle defaults exclude paths into configulator's own source
+        // (only meaningful when configulator is a workspace package,
+        // i.e. in codedrifters/packages itself). That repo restores
+        // them via `agentConfig.additionalRulePaths`; other consumers
+        // get a clean default.
+        filePatterns: [".claude/agents/*.md", ".claude/procedures/**"],
         content: renderProgressFilesRuleContent(resolveProgressFiles()),
         platforms: {
           cursor: { exclude: true }
@@ -4495,27 +4498,26 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         name: "shared-editing-safety",
         description: "Shared-editing safety: single-entry deterministic-sort inserts on index files, commit-path verification, and the merge-conflict resolution recipe that keeps concurrent agent sessions from dropping each other's rows on shared registries and feature matrices.",
-        scope: AGENT_RULE_SCOPE.ALWAYS,
+        scope: AGENT_RULE_SCOPE.FILE_PATTERN,
+        filePatterns: DEFAULT_SHARED_INDEX_PATHS,
         content: renderSharedEditingRuleContent(resolveSharedEditing()),
         platforms: {
           cursor: { exclude: true }
         },
         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: "temporal-framing-convention",
         description: "Temporal-framing convention: every agent-authored time-sensitive factual claim (ownership, leadership tenure, regulatory status, litigation, dated metrics) carries an inline `as of [YYYY-MM-DD]` or `as of [Month YYYY]` qualifier on first occurrence so refresh agents have a mechanical signal for which claims to re-verify.",
-        scope: AGENT_RULE_SCOPE.ALWAYS,
+        scope: AGENT_RULE_SCOPE.FILE_PATTERN,
+        filePatterns: [
+          "docs/src/content/docs/profiles/**/*.md",
+          "docs/src/content/docs/industry-research/**/*.md",
+          "docs/src/content/docs/software-research/**/*.md",
+          "docs/src/content/docs/regulatory-research/**/*.md",
+          "docs/src/content/docs/standards-research/**/*.md",
+          "docs/src/content/docs/customer-research/**/*.md"
+        ],
         content: renderTemporalFramingRuleContent(resolveTemporalFraming()),
         platforms: {
           cursor: { exclude: true }
@@ -4525,7 +4527,10 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         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.",
-        scope: AGENT_RULE_SCOPE.ALWAYS,
+        scope: AGENT_RULE_SCOPE.FILE_PATTERN,
+        // Bundle defaults exclude paths into configulator's own
+        // source — see comment on progress-file-convention above.
+        filePatterns: [".claude/skills/**"],
         content: renderSkillEvalsRuleContent(resolveSkillEvals()),
         platforms: {
           cursor: { exclude: true }
@@ -4535,7 +4540,14 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
       {
         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.`,
-        scope: AGENT_RULE_SCOPE.ALWAYS,
+        scope: AGENT_RULE_SCOPE.FILE_PATTERN,
+        // Bundle defaults exclude paths into configulator's own
+        // source — see comment on progress-file-convention above.
+        filePatterns: [
+          ".claude/skills/**/SKILL.md",
+          ".claude/agents/*.md",
+          `${paths.docsRoot}/agents/issue-templates.md`
+        ],
         content: renderIssueTemplatesRuleContent(resolveIssueTemplates()),
         platforms: {
           cursor: { exclude: true }
@@ -5858,8 +5870,8 @@ function buildBusinessModelsAnalystSubAgent(paths) {
       "",
       "7. **Create the segment index** at",
       "   `<BUSINESS_MODELS_ROOT>/<industry>/segments/<SEGMENT_SLUG>/index.md`",
-      "   if it does not already exist. Follow the",
-      "   `stub-index-convention` rule: a 1\u20132 paragraph summary of the",
+      "   if it does not already exist. Follow the section-index-page",
+      "   contract in the `shared-editing-safety` 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",
@@ -10226,6 +10238,10 @@ var githubWorkflowBundle = {
     {
       name: "create-issue-workflow",
       description: "Automated workflow for creating a new GitHub issue",
+      // ALWAYS scope: users invoke "create an issue" from any
+      // context, not only when editing agent / skill / bundle source.
+      // Consumers that want to narrow the load can override via
+      // `agentConfig.additionalRulePaths` or `excludeRules`.
       scope: AGENT_RULE_SCOPE.ALWAYS,
       content: [
         "# Create Issue Workflow",
@@ -16256,7 +16272,15 @@ var orchestratorBundle = {
     {
       name: "orchestrator-conventions",
       description: "Guidelines for orchestrator agent behavior and pipeline management, including the funnel-tier dispatch sort, scope gate, and per-agent scheduled-task layout",
-      scope: AGENT_RULE_SCOPE.ALWAYS,
+      scope: AGENT_RULE_SCOPE.FILE_PATTERN,
+      // Bundle defaults exclude paths into configulator's own source
+      // (only meaningful when configulator is a workspace package).
+      // codedrifters/packages restores them via
+      // `agentConfig.additionalRulePaths`.
+      filePatterns: [
+        ".claude/agents/orchestrator.md",
+        ".claude/scheduled-tasks/**"
+      ],
       content: buildOrchestratorConventionsContent(
         DEFAULT_AGENT_TIERS,
         resolveScopeGate(),
@@ -16265,7 +16289,6 @@ var orchestratorBundle = {
         resolveUnblockDependents()
       ),
       platforms: {
-        claude: { target: "claude-md" },
         cursor: { exclude: true }
       },
       tags: ["workflow"]
@@ -18836,7 +18859,15 @@ function buildPrReviewBundle(policy = resolvePrReviewPolicy()) {
       {
         name: "pr-review-policy",
         description: "Declarative policy that tells the pr-reviewer which PRs may auto-merge and which must wait for a human reviewer",
-        scope: AGENT_RULE_SCOPE.ALWAYS,
+        scope: AGENT_RULE_SCOPE.FILE_PATTERN,
+        // Bundle defaults exclude paths into configulator's own source
+        // (only meaningful when configulator is a workspace package).
+        // codedrifters/packages restores them via
+        // `agentConfig.additionalRulePaths`.
+        filePatterns: [
+          ".claude/agents/pr-reviewer.md",
+          ".claude/skills/review-pr/**"
+        ],
         content: [
           "# PR Review Policy",
           "",
@@ -19018,7 +19049,15 @@ function buildPrReviewBundle(policy = resolvePrReviewPolicy()) {
       {
         name: "pr-review-feedback-protocol",
         description: "Documents the human-in-the-loop feedback loop on PR review: reaction state machine, pushback resolution, fix-list comment format, sticky reviewer-notes comment, label glossary, and human-author opt-in flag.",
-        scope: AGENT_RULE_SCOPE.ALWAYS,
+        scope: AGENT_RULE_SCOPE.FILE_PATTERN,
+        // Bundle defaults exclude paths into configulator's own source
+        // (only meaningful when configulator is a workspace package).
+        // codedrifters/packages restores them via
+        // `agentConfig.additionalRulePaths`.
+        filePatterns: [
+          ".claude/agents/pr-reviewer.md",
+          ".claude/agents/issue-worker.md"
+        ],
         content: [
           "# PR Review Feedback Protocol",
           "",
@@ -19253,6 +19292,10 @@ var projenBundle = {
     {
       name: "development-commands",
       description: "Projen development commands for building, testing, linting, and validating changes",
+      // ALWAYS scope: developers ask "how do I build/test/lint?" from
+      // anywhere in the repo, not only when editing projen config.
+      // Consumers that want to narrow the load can override via
+      // `agentConfig.additionalRulePaths` or `excludeRules`.
       scope: AGENT_RULE_SCOPE.ALWAYS,
       content: [
         "# Development Commands",
@@ -19961,7 +20004,8 @@ function buildRegulatoryResearchAnalystSubAgent(paths, issueDefaults) {
       "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. Follow the",
-      "   `stub-index-convention` rule: the body must carry a 1\u20132",
+      "   section-index-page contract in the `shared-editing-safety` 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",
@@ -27446,7 +27490,8 @@ function buildStandardsResearchAnalystSubAgent(paths, issueDefaults) {
       "   pages.",
       "",
       "4. **Write the overview page** at `<OVERVIEW_PAGE>`. Follow",
-      "   the `stub-index-convention` rule: the body opens with a",
+      "   the section-index-page contract in the",
+      "   `shared-editing-safety` 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",
@@ -29279,6 +29324,62 @@ function bundleNameForWorkflowRule(ruleName) {
   );
   return entry?.bundle;
 }
+function buildConventionsRegistryRule(rules) {
+  const entries = [];
+  for (const rule of rules) {
+    if (rule.scope !== AGENT_RULE_SCOPE.FILE_PATTERN) {
+      continue;
+    }
+    if (rule.platforms?.claude?.exclude === true) {
+      continue;
+    }
+    if (!rule.filePatterns || rule.filePatterns.length === 0) {
+      continue;
+    }
+    entries.push(rule);
+  }
+  if (entries.length === 0) {
+    return void 0;
+  }
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  const lines = [
+    "# Conventions Registry",
+    "",
+    "Each row below is a `FILE_PATTERN`-scoped convention rule that",
+    "auto-loads on demand when the agent's current file matches one",
+    "of the listed paths. Full rule bodies live under",
+    "`.claude/rules/<slug>.md` so they only consume context when",
+    "they apply. Consult the matching rule before doing work in any",
+    "of the listed surfaces.",
+    "",
+    "| Rule | Auto-loads when editing | Purpose |",
+    "| --- | --- | --- |"
+  ];
+  const MAX_PATTERNS_SHOWN = 3;
+  for (const rule of entries) {
+    const ruleLink = `[\`${rule.name}\`](.claude/rules/${rule.name}.md)`;
+    const patterns = rule.filePatterns ?? [];
+    let patternCell;
+    if (patterns.length <= MAX_PATTERNS_SHOWN) {
+      patternCell = patterns.map((p) => `\`${p}\``).join(", ");
+    } else {
+      const shown = patterns.slice(0, MAX_PATTERNS_SHOWN).map((p) => `\`${p}\``).join(", ");
+      patternCell = `${shown}, \u2026 ([full list](.claude/rules/${rule.name}.md))`;
+    }
+    const purposeCell = rule.description.replace(/\s+/g, " ").replace(/\|/g, "\\|").trim();
+    lines.push(`| ${ruleLink} | ${patternCell} | ${purposeCell} |`);
+  }
+  return {
+    name: "conventions-registry",
+    description: "Routing table for every FILE_PATTERN-scoped convention rule. Lists each rule's slug, the file patterns that auto-trigger it, and a one-line purpose so agents whose current file does not match any rule's paths: can still discover the full convention set.",
+    scope: AGENT_RULE_SCOPE.ALWAYS,
+    content: lines.join("\n"),
+    platforms: {
+      cursor: { exclude: true }
+    },
+    tags: ["workflow"]
+  };
+}
 function buildAgentRegistryRule(bundles, paths) {
   const activeNames = new Set(bundles.map((b) => b.name));
   const rows = AGENT_REGISTRY_ENTRIES.filter(
@@ -31001,6 +31102,20 @@ ${extra}`
         }
       }
     }
+    if (this.options.additionalRulePaths) {
+      for (const [name, extraPaths] of Object.entries(
+        this.options.additionalRulePaths
+      )) {
+        if (extraPaths.length === 0) continue;
+        const existing = ruleMap.get(name);
+        if (!existing) continue;
+        if (existing.scope !== AGENT_RULE_SCOPE.FILE_PATTERN) continue;
+        ruleMap.set(name, {
+          ...existing,
+          filePatterns: [...existing.filePatterns ?? [], ...extraPaths]
+        });
+      }
+    }
     if (this.options.priorityRules && this.options.priorityRules.length > 0) {
       const issueLabelRule = ruleMap.get("issue-label-conventions");
       if (issueLabelRule) {
@@ -31207,9 +31322,6 @@ ${hook}`
         }
       }
     }
-    if (!hasAnyDocsEmittingBundle(excludedBundleNames)) {
-      ruleMap.delete("stub-index-convention");
-    }
     if (injectBundleHooks && resolvedIssueTemplatesForRules.enabled && hasDownstreamBundles) {
       for (const [ruleName, label] of ISSUE_TEMPLATES_BUNDLE_HOOKS) {
         const existing = ruleMap.get(ruleName);
@@ -31326,6 +31438,12 @@ ${meetingsSection}`;
         });
       }
     }
+    const conventionsRegistryRule = buildConventionsRegistryRule(
+      ruleMap.values()
+    );
+    if (conventionsRegistryRule) {
+      ruleMap.set(conventionsRegistryRule.name, conventionsRegistryRule);
+    }
     return [...ruleMap.values()].sort((a, b) => {
       if (a.name === "project-overview") return -1;
       if (b.name === "project-overview") return 1;
@@ -37560,7 +37678,6 @@ export {
   renderSkillEvalsRuleContent,
   renderSkillEvalsRunnerScript,
   renderSourceTierExamples,
-  renderStubIndexConventionRuleContent,
   renderTemporalFramingCheckerScript,
   renderTemporalFramingRuleContent,
   renderUnblockDependentsScript,