paqad-ai 1.41.1 → 1.43.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # paqad-ai
 
+## 1.43.0
+
+### Minor Changes
+
+- 3bc15df: Publish two measured, reproducible benchmark numbers with methodology and caveats
+  (issue #285). Adds read-only repo tooling: `scripts/measure-footprint.mjs` reports the
+  resident session-start token footprint per area (real tokenizer via
+  `src/context/tokenizer-cache.ts`, labelled char/4 fallback), and
+  `scripts/rule-findings-stats.mjs` reads the existing `rule-evidence` ledger via
+  `readProjectEvents` and buckets deterministic findings by ISO week. Results, method, run
+  counts, tokenizer version, per-tier applicability, and caveats live in
+  `docs/instructions/benchmarks/measured.md`. The two unbenchmarked "60-85%" README claims
+  are replaced with the measured 49-61% resident-load reduction and a link to the method.
+  No product behavior changes; `rag_enabled` stays default off.
+
+## 1.42.0
+
+### Minor Changes
+
+- 561665d: Token-neutral by default: lean rule loading is now the default delivery path (issue #284).
+
+  A new `lean_rules` flag (default **on**, env `PAQAD_LEAN_RULES`) makes the always-resident rule manifest plus trigger-loaded applicable rule text the default, instead of loading the whole `docs/instructions/rules` tree every session. The framework bootstrap and the Claude Code prompt-gate now read `.paqad/context/session-context.md` artifact-first, falling back to the full rule load only when the artifact is missing. On Claude Code the session-time seam and the background refresh trigger are ungated from `rag_enabled` so the rule slice is injected and kept current with no embedding, index, or provider call on the lean path; `rag_enabled` continues to govern only what retrieval/memory/drift sections compose into the same artifact. A committed resident-footprint budget test and a `paqad-ai doctor` readout gate the token cost. `lean_rules=false` restores the previous full-load behaviour exactly, and paqad-disabled stays a pure no-op.
+
 ## 1.41.1
 
 ### Patch Changes

package/README.md

@@ -52,16 +52,16 @@ No account, no API key, no subscription. Prefer not to install anything? Run `np
 
 ## What you get, at a glance
 
-| Area                         | What it means for you                                                            |
-| ---------------------------- | -------------------------------------------------------------------------------- |
-| **One setup, every tool**    | Configure Claude, Cursor, Copilot, Gemini, and the rest from one source of truth |
-| **Workflows, not prompts**   | Your team's process runs the same way every time, instead of being re-typed      |
-| **Proof, not promises**      | Automatic checks confirm tests, specs, docs, and security before "done" counts   |
-| **Security as a workflow**   | A full OWASP pentest pass, with retests, built in                                |
-| **Design as a workflow**     | Your UI audited against your own design system                                   |
-| **Docs that stay current**   | The framework keeps your documentation in sync with the code                     |
-| **Fewer tokens, on purpose** | Loads the right files, not the whole repo, cutting token use by 60-85%           |
-| **Runs locally**             | Your code stays on your machine, with an audit trail you can keep                |
+| Area                         | What it means for you                                                                  |
+| ---------------------------- | -------------------------------------------------------------------------------------- |
+| **One setup, every tool**    | Configure Claude, Cursor, Copilot, Gemini, and the rest from one source of truth       |
+| **Workflows, not prompts**   | Your team's process runs the same way every time, instead of being re-typed            |
+| **Proof, not promises**      | Automatic checks confirm tests, specs, docs, and security before "done" counts         |
+| **Security as a workflow**   | A full OWASP pentest pass, with retests, built in                                      |
+| **Design as a workflow**     | Your UI audited against your own design system                                         |
+| **Docs that stay current**   | The framework keeps your documentation in sync with the code                           |
+| **Fewer tokens, on purpose** | Loads a lean resident slice, not the whole repo. Measured 49-61% smaller resident load |
+| **Runs locally**             | Your code stays on your machine, with an audit trail you can keep                      |
 
 The rest of this page walks through each of these. The [full docs](https://paqad.ai/docs.html) go deeper on every command and concept.
 
@@ -267,7 +267,13 @@ Documentation is a real output here, not an afterthought you maintain by hand. A
 
 ## The right context, with fewer tokens
 
-Your agent does not need your whole repo. It needs the right files. And since every model gets worse on a bloated context, loading less is not just cheaper, it makes the answers better. paqad-ai cuts token use by **60-85%** through careful context loading.
+Your agent does not need your whole repo. It needs the right files. And since every model gets worse on a bloated context, loading less is not just cheaper, it makes the answers better.
+
+paqad-ai keeps the session-start load lean: a rule manifest plus the files a task actually touches, instead of the whole rule tree. Measured across two projects, that resident load is **49-61% smaller** than loading everything (paqad-ai's own repo: 61%; a fresh React onboard: 49%). Both used the char/4 heuristic tokenizer, so treat them as an honest floor, not a marketing ceiling. The method, the per-project numbers, and the caveats are in [`docs/instructions/benchmarks/measured.md`](docs/instructions/benchmarks/measured.md), and you can reproduce them in your own repo:
+
+```
+node scripts/measure-footprint.mjs --project .
+```
 
 - It splits files at natural boundaries (functions and classes), not at arbitrary line counts.
 - It ranks each piece by five signals: meaning, keywords, the symbols involved, how close the file is to the task, and how deeply nested it is.

package/dist/cli/index.js

@@ -665,7 +665,8 @@ function resolveFrameworkConfigFromMap(raw) {
       market_research: rb("market_research"),
       design_research: rb("design_research"),
       team_agents: rb("team_agents"),
-      analytics_instrumentation: rb("analytics_instrumentation")
+      analytics_instrumentation: rb("analytics_instrumentation"),
+      lean_rules: rb("lean_rules")
     },
     research: {
       depth: asEnum(
@@ -1023,6 +1024,7 @@ function frameworkOverridesToFlat(overrides) {
       f.analytics_instrumentation,
       d.features.analytics_instrumentation
     );
+    put("lean_rules", f.lean_rules, d.features.lean_rules);
   }
   if (overrides.research) {
     put("research_depth", overrides.research.depth, d.research.depth);
@@ -1233,6 +1235,15 @@ var init_framework_config = __esm({
         section: "Feature flags",
         comment: "Opt in to complementary analytics instrumentation (issue #241, refined #279). OFF (default) is silent; ON authorizes wiring tracking + a per-event tracking-plan doc."
       },
+      {
+        key: "lean_rules",
+        env: "PAQAD_LEAN_RULES",
+        type: "boolean",
+        default: true,
+        group: "app",
+        section: "Feature flags",
+        comment: "Token-neutral rule loading (issue #284). ON (default) delivers the lean rule contract (manifest + only the rule text that applies to the files in play) and lifts the full-load mandate. OFF restores loading docs/instructions/rules in full every session."
+      },
       // ── rag group ──────────────────────────────────────────────────────────
       {
         key: "rag_enabled",
@@ -1580,7 +1591,8 @@ var init_framework_config = __esm({
           "market_research",
           "design_research",
           "team_agents",
-          "analytics_instrumentation"
+          "analytics_instrumentation",
+          "lean_rules"
         ]
       },
       { present: (p) => p.research !== void 0, keys: ["research_depth"] },
@@ -3464,7 +3476,8 @@ var init_project_profile_schema = __esm({
             market_research: { type: "boolean" },
             design_research: { type: "boolean" },
             team_agents: { type: "boolean" },
-            analytics_instrumentation: { type: "boolean" }
+            analytics_instrumentation: { type: "boolean" },
+            lean_rules: { type: "boolean" }
           }
         },
         enterprise: {
@@ -18266,6 +18279,7 @@ var HealthChecker = class {
       this.checkMcp(projectRoot, profile),
       this.checkSkillCache(projectRoot),
       this.checkContextHitRate(projectRoot, profile),
+      this.checkLeanRuleFootprint(projectRoot),
       this.checkClassificationOverrideRate(projectRoot),
       ...await this.checkRag(projectRoot, profile)
     ];
@@ -18794,6 +18808,37 @@ var HealthChecker = class {
       mcp_usage_rate: 0
     };
   }
+  /**
+   * Issue #284 — the resident rule-footprint readout. Reports how many bytes the lean
+   * session-context artifact carries versus loading the full `docs/instructions/rules`
+   * tree, computed per project (no hard-coded sizes). A present, smaller artifact is a
+   * pass with the savings; an artifact that is not smaller than the full rule set warns
+   * (lean loading is not paying off). A missing artifact is a pass: full-load is the
+   * documented fallback and the artifact regenerates on the next refresh/onboard.
+   */
+  checkLeanRuleFootprint(projectRoot) {
+    const name = "Lean rule footprint acceptable";
+    const rulesRoot = join58(projectRoot, PATHS.RULES_DIR);
+    if (!existsSync32(rulesRoot)) {
+      return pass(name, "No rules directory to load \u2014 nothing to slim");
+    }
+    const fullRulesBytes = walk2(rulesRoot).filter((file) => file.endsWith(".md")).reduce((sum2, file) => sum2 + statSync4(file).size, 0);
+    const artifactPath = join58(projectRoot, PATHS.CONTEXT_SESSION_ARTIFACT);
+    if (!existsSync32(artifactPath)) {
+      return pass(
+        name,
+        "Lean rule artifact not generated yet \u2014 full rule load is the fallback until the next refresh"
+      );
+    }
+    const residentBytes = statSync4(artifactPath).size;
+    const pct = fullRulesBytes > 0 ? Math.round(residentBytes / fullRulesBytes * 100) : 0;
+    const detail = `Resident rule context is ${residentBytes} bytes vs ${fullRulesBytes} bytes for the full rule set (${pct}% of full)`;
+    return residentBytes < fullRulesBytes || fullRulesBytes === 0 ? pass(name, detail) : warn(
+      name,
+      `${detail} \u2014 lean loading is not reducing the resident footprint`,
+      "Ensure lean_rules is on and re-run `paqad-ai rag refresh-context` to recompose the lean artifact."
+    );
+  }
   checkClassificationOverrideRate(projectRoot) {
     const path11 = join58(projectRoot, PATHS.AGENCY_CACHE_DIR, "classification-history.json");
     if (!existsSync32(path11)) {
@@ -23982,7 +24027,8 @@ function buildProjectProfile(selections, snapshot, overrides, projectRoot) {
       market_research: false,
       design_research: false,
       team_agents: true,
-      analytics_instrumentation: false
+      analytics_instrumentation: false,
+      lean_rules: true
     },
     // Issue #187 — emit the enterprise block at onboarding so the opt-in
     // evidence-ledger / AI-BOM / compliance-citation switches are visible and
@@ -26076,7 +26122,7 @@ init_cancelled_error();
 init_events();
 
 // src/index.ts
-var VERSION = "1.41.1";
+var VERSION = "1.43.0";
 
 // src/cli/commands/audit.ts
 init_esm_shims();
@@ -33845,6 +33891,7 @@ import { readFileSync as readFileSync76 } from "fs";
 import { isAbsolute as isAbsolute5, join as join174 } from "path";
 import { confirm, input as input2, select as select3 } from "@inquirer/prompts";
 import { Command as Command18 } from "commander";
+init_framework_config();
 
 // src/context/codebase-memory.ts
 init_esm_shims();
@@ -34808,6 +34855,17 @@ function createRagCommand() {
   command.command("refresh-context").description(
     "Sync the index, retrieve slices, and recompose session context (background worker)"
   ).option("--project-root <path>", "Project root", process.cwd()).option("--quiet", "Suppress output (used by the background trigger)").action(async (options) => {
+    const ragEnabled = resolveFrameworkConfig(options.projectRoot).intelligence.rag_enabled;
+    if (!ragEnabled) {
+      const target2 = await refreshRuleContext(options.projectRoot, {});
+      if (!options.quiet) {
+        process.stdout.write(
+          `${target2 ? `wrote ${target2}` : "nothing to compose"}; rule-only (rag off)
+`
+        );
+      }
+      return;
+    }
     const sync = await backgroundIndexSync(options.projectRoot);
     const slices = await gatherWorkingSetSlices(options.projectRoot, {
       recordEvidence: { adapter: "engine" }