compose-agentsmd 5.0.0 → 6.0.0

package/README.md

@@ -116,14 +116,14 @@ Ruleset keys:
 - `domains` (optional): domain folders under `rules/domains/<domain>`.
 - `extra` (optional): additional local rule files to append.
 - `budget` (optional): global-rule budget thresholds in `o200k_base` tokens.
-- `budget.totalTokens` (optional): total token budget for the composed global instruction output (defaults to `4500`).
-- `budget.moduleTokens` (optional): per-module token budget for each composed global rule section (defaults to `400`).
+- `budget.totalTokens` (optional): hard total token budget for the composed global instruction output (defaults to `8000`). Exceeding this is reported as a budget violation.
+- `budget.moduleTokens` (optional): per-module advisory threshold for each composed global rule section (defaults to `800`). Crossing this is **not** a violation; it triggers a review prompt to check whether the listed modules contain procedural content that should move to skills (procedures belong in skills, not rules).
 - `claude` (optional): repository companion settings for Claude Code.
 - `claude.enabled` (optional): enable/disable companion generation (defaults to `true`).
 - `claude.output` (optional): companion file path (defaults to `CLAUDE.md`).
 - `output` (optional): repository output file name (defaults to `AGENTS.md`).
 
-When the composed global instruction output exceeds either budget, the CLI emits a warning to `stderr`. The machine-readable `--json` output includes the tokenizer name, total token count, and any over-budget modules.
+When the composed global instruction output exceeds the total budget, the CLI emits a `⚠ Global rules budget exceeded` warning to `stderr`. When any module crosses the per-module advisory threshold, the CLI emits a separate `ℹ Modules over per-module review threshold` advisory to `stderr`. Both can be suppressed with `--quiet`. The machine-readable `--json` output includes `budget.totalExceeded`, `budget.moduleReviewTriggered`, the tokenizer name, total token count, and any over-threshold modules.
 
 ### Ruleset schema validation
 

package/dist/compose-agents.js

@@ -25,8 +25,17 @@ const PACKAGE_JSON_PATH = new URL("../package.json", import.meta.url);
 const TOOL_RULES_PATH = new URL("../tools/tool-rules.md", import.meta.url);
 const USAGE_PATH = new URL("../tools/usage.txt", import.meta.url);
 const BUDGET_TOKENIZER = "o200k_base";
-const DEFAULT_TOTAL_BUDGET = 4500;
-const DEFAULT_MODULE_BUDGET = 400;
+// Token budgets for the composed global rules.
+// - DEFAULT_TOTAL_BUDGET: hard budget for the always-loaded global rules.
+//   Sized to accommodate realistic invariant density (~80–120 invariants ×
+//   ~30–50 tokens each ≈ 5–6k tokens) plus structural margin and growth
+//   headroom, while staying a small fraction of the smallest target model's
+//   effective system-prompt window. Total exceedance is a budget violation.
+// - DEFAULT_MODULE_BUDGET: per-module advisory threshold, NOT a violation.
+//   Crossing it triggers a review prompt to check whether the module is
+//   leaking procedural content (procedures belong in skills, not rules).
+const DEFAULT_TOTAL_BUDGET = 8000;
+const DEFAULT_MODULE_BUDGET = 800;
 const LINT_HEADER = "<!-- markdownlint-disable MD025 -->";
 const readValueArg = (remaining, index, flag) => {
     const value = remaining[index + 1];
@@ -671,7 +680,8 @@ const composeRuleset = (rulesetPath, rootDir, options) => {
         totalBudget,
         moduleBudget,
         overBudgetModules,
-        exceeded: totalTokens > totalBudget || overBudgetModules.length > 0
+        totalExceeded: totalTokens > totalBudget,
+        moduleReviewTriggered: overBudgetModules.length > 0
     };
     const repositoryOutputs = [toDisplayPath(rootDir, primaryOutputPath)];
     const globalOutputs = globalOutputPaths.map((filePath) => toDisplayPath(rootDir, filePath));
@@ -759,18 +769,20 @@ const formatComposedOutputs = (result) => {
     }
     return `${lines.join("\n")}\n`;
 };
-const formatBudgetWarning = (result) => {
-    const totalInfo = result.totalTokens > result.totalBudget
-        ? `: ${result.totalTokens}/${result.totalBudget} tokens`
-        : "";
-    const lines = [`⚠ Global rules budget exceeded (${result.tokenizer})${totalInfo}`];
-    if (result.overBudgetModules.length > 0) {
-        lines.push(`  Over-budget modules (> ${result.moduleBudget} tokens):`);
+const formatBudgetReport = (result) => {
+    const lines = [];
+    if (result.totalExceeded) {
+        lines.push(`⚠ Global rules budget exceeded (${result.tokenizer}): ` +
+            `${result.totalTokens}/${result.totalBudget} tokens`);
+    }
+    if (result.moduleReviewTriggered) {
+        lines.push(`ℹ Modules over per-module review threshold (> ${result.moduleBudget} tokens, advisory):`);
         for (const mod of result.overBudgetModules) {
             lines.push(`    ${mod.name}: ${mod.tokens} tokens`);
         }
+        lines.push("  Review whether listed modules contain procedural content that should move to skills.");
     }
-    return `${lines.join("\n")}\n`;
+    return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
 };
 const LOCAL_RULES_TEMPLATE = "# Local Rules\n\n- Add project-specific instructions here.\n";
 const buildInitRuleset = (args) => {
@@ -951,8 +963,9 @@ const initProject = async (args, rootDir, rulesetName) => {
         if (composedOutput) {
             process.stdout.write(formatComposedOutputs(composedOutput));
             printOutputDiffs(composedOutput);
-            if (composedOutput.budgetResult.exceeded) {
-                process.stderr.write(formatBudgetWarning(composedOutput.budgetResult));
+            if (composedOutput.budgetResult.totalExceeded ||
+                composedOutput.budgetResult.moduleReviewTriggered) {
+                process.stderr.write(formatBudgetReport(composedOutput.budgetResult));
             }
         }
     }
@@ -1051,8 +1064,8 @@ const main = async () => {
         else if (!args.quiet) {
             process.stdout.write(formatComposedOutputs(output));
             printOutputDiffs(output);
-            if (output.budgetResult.exceeded) {
-                process.stderr.write(formatBudgetWarning(output.budgetResult));
+            if (output.budgetResult.totalExceeded || output.budgetResult.moduleReviewTriggered) {
+                process.stderr.write(formatBudgetReport(output.budgetResult));
             }
         }
         return;
@@ -1088,8 +1101,8 @@ const main = async () => {
             printOutputDiffs(result);
         }
         for (const result of outputs) {
-            if (result.budgetResult.exceeded) {
-                process.stderr.write(formatBudgetWarning(result.budgetResult));
+            if (result.budgetResult.totalExceeded || result.budgetResult.moduleReviewTriggered) {
+                process.stderr.write(formatBudgetReport(result.budgetResult));
             }
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compose-agentsmd",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "CLI tools for composing repository-local and user-global agent instruction files from modular rule sets",
   "license": "MIT",
   "repository": {