@mrclrchtr/supi-claude-md 1.7.0 → 1.8.0

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -37,8 +37,19 @@
   "main": "src/api.ts",
   "exports": {
     "./api": "./src/api.ts",
+    "./config": "./src/config.ts",
+    "./context": "./src/context.ts",
+    "./debug": "./src/debug-registry.ts",
     "./extension": "./src/extension.ts",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./path": "./src/path.ts",
+    "./project": "./src/project.ts",
+    "./session": "./src/session.ts",
+    "./settings": "./src/settings.ts",
+    "./settings-ui": "./src/settings-ui.ts",
+    "./terminal": "./src/terminal.ts",
+    "./tool-framework": "./src/tool-framework.ts",
+    "./types": "./src/types.ts"
   },
   "pi": {
     "extensions": [

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -1,96 +1,30 @@
 // supi-core — shared infrastructure for SuPi extensions.
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
+//
+// Convenience barrel — re-exports all domain entry points.
+// For lighter imports, use one of the domain subpaths directly
+// (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
-export {
-  loadSupiConfig,
-  loadSupiConfigForScope,
-  readJsonFile,
-  removeSupiConfigKey,
-  writeSupiConfig,
-} from "./config/config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
-export { registerConfigSettings } from "./config/config-settings.ts";
-export type { ContextMessageLike } from "./context/context-messages.ts";
-export {
-  findLastUserMessageIndex,
-  getContextToken,
-  getPromptContent,
-  pruneAndReorderContextMessages,
-  restorePromptContent,
-} from "./context/context-messages.ts";
-export type { ContextProvider } from "./context/context-provider-registry.ts";
-export {
-  clearRegisteredContextProviders,
-  getRegisteredContextProviders,
-  registerContextProvider,
-} from "./context/context-provider-registry.ts";
-export { wrapExtensionContext } from "./context/context-tag.ts";
-export type {
-  DebugAgentAccess,
-  DebugEvent,
-  DebugEventInput,
-  DebugEventQuery,
-  DebugEventQueryResult,
-  DebugEventView,
-  DebugLevel,
-  DebugNotifyLevel,
-  DebugRegistryConfig,
-  DebugSummary,
-} from "./debug-registry.ts";
-export {
-  clearDebugEvents,
-  configureDebugRegistry,
-  DEBUG_REGISTRY_DEFAULTS,
-  getDebugEvents,
-  getDebugRegistryConfig,
-  getDebugSummary,
-  recordDebugEvent,
-  redactDebugData,
-  resetDebugRegistry,
-} from "./debug-registry.ts";
-export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
-export type { KnownRootEntry } from "./project-roots.ts";
-export {
-  buildKnownRootsMap,
-  byPathDepth,
-  dedupeTopmostRoots,
-  findProjectRoot,
-  isWithin,
-  isWithinOrEqual,
-  mergeKnownRoots,
-  resolveKnownRoot,
-  segmentCount,
-  sortRootsBySpecificity,
-  walkProject,
-} from "./project-roots.ts";
-export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
-export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings/settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
-export {
-  clearRegisteredSettings,
-  getRegisteredSettings,
-  registerSettings,
-} from "./settings/settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
-export type { TitleTarget } from "./terminal.ts";
-export {
-  DONE_SYMBOL,
-  formatTitle,
-  signalBell,
-  signalDone,
-  signalWaiting,
-  WAITING_SYMBOL,
-} from "./terminal.ts";
-export type { SuiPiToolPromptSurface, SuiPiToolSpec, ToolExecuteFn } from "./tool-framework.ts";
-export {
-  CharacterParam,
-  derivePromptSurface,
-  FileParam,
-  LineParam,
-  MaxResultsParam,
-  registerSuiPiTools,
-  SymbolParam,
-} from "./tool-framework.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./config.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./context.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./debug-registry.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./path.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./project.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./session.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings-ui.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./terminal.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./tool-framework.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./types.ts";

package/node_modules/@mrclrchtr/supi-core/src/config.ts

@@ -0,0 +1,11 @@
+// supi-core config domain — config loading and config-settings helpers.
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
+export {
+  loadSupiConfig,
+  loadSupiConfigForScope,
+  readJsonFile,
+  removeSupiConfigKey,
+  writeSupiConfig,
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";

package/node_modules/@mrclrchtr/supi-core/src/context.ts

@@ -0,0 +1,16 @@
+// supi-core context domain — context messages, providers, and XML tags.
+export type { ContextMessageLike } from "./context/context-messages.ts";
+export {
+  findLastUserMessageIndex,
+  getContextToken,
+  getPromptContent,
+  pruneAndReorderContextMessages,
+  restorePromptContent,
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
+export {
+  clearRegisteredContextProviders,
+  getRegisteredContextProviders,
+  registerContextProvider,
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -1,96 +1,30 @@
 // supi-core — shared infrastructure for SuPi extensions.
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
+//
+// Convenience barrel — re-exports all domain entry points.
+// For lighter imports, use one of the domain subpaths directly
+// (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
-export {
-  loadSupiConfig,
-  loadSupiConfigForScope,
-  readJsonFile,
-  removeSupiConfigKey,
-  writeSupiConfig,
-} from "./config/config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
-export { registerConfigSettings } from "./config/config-settings.ts";
-export type { ContextMessageLike } from "./context/context-messages.ts";
-export {
-  findLastUserMessageIndex,
-  getContextToken,
-  getPromptContent,
-  pruneAndReorderContextMessages,
-  restorePromptContent,
-} from "./context/context-messages.ts";
-export type { ContextProvider } from "./context/context-provider-registry.ts";
-export {
-  clearRegisteredContextProviders,
-  getRegisteredContextProviders,
-  registerContextProvider,
-} from "./context/context-provider-registry.ts";
-export { wrapExtensionContext } from "./context/context-tag.ts";
-export type {
-  DebugAgentAccess,
-  DebugEvent,
-  DebugEventInput,
-  DebugEventQuery,
-  DebugEventQueryResult,
-  DebugEventView,
-  DebugLevel,
-  DebugNotifyLevel,
-  DebugRegistryConfig,
-  DebugSummary,
-} from "./debug-registry.ts";
-export {
-  clearDebugEvents,
-  configureDebugRegistry,
-  DEBUG_REGISTRY_DEFAULTS,
-  getDebugEvents,
-  getDebugRegistryConfig,
-  getDebugSummary,
-  recordDebugEvent,
-  redactDebugData,
-  resetDebugRegistry,
-} from "./debug-registry.ts";
-export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
-export type { KnownRootEntry } from "./project-roots.ts";
-export {
-  buildKnownRootsMap,
-  byPathDepth,
-  dedupeTopmostRoots,
-  findProjectRoot,
-  isWithin,
-  isWithinOrEqual,
-  mergeKnownRoots,
-  resolveKnownRoot,
-  segmentCount,
-  sortRootsBySpecificity,
-  walkProject,
-} from "./project-roots.ts";
-export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
-export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings/settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
-export {
-  clearRegisteredSettings,
-  getRegisteredSettings,
-  registerSettings,
-} from "./settings/settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
-export type { TitleTarget } from "./terminal.ts";
-export {
-  DONE_SYMBOL,
-  formatTitle,
-  signalBell,
-  signalDone,
-  signalWaiting,
-  WAITING_SYMBOL,
-} from "./terminal.ts";
-export type { SuiPiToolPromptSurface, SuiPiToolSpec, ToolExecuteFn } from "./tool-framework.ts";
-export {
-  CharacterParam,
-  derivePromptSurface,
-  FileParam,
-  LineParam,
-  MaxResultsParam,
-  registerSuiPiTools,
-  SymbolParam,
-} from "./tool-framework.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./config.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./context.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./debug-registry.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./path.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./project.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./session.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings-ui.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./terminal.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./tool-framework.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./types.ts";

package/node_modules/@mrclrchtr/supi-core/src/path.ts

@@ -0,0 +1,2 @@
+// supi-core path domain — file and URI path utilities.
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";

package/node_modules/@mrclrchtr/supi-core/src/project.ts

@@ -0,0 +1,15 @@
+// supi-core project domain — project root discovery and traversal.
+export type { KnownRootEntry } from "./project-roots.ts";
+export {
+  buildKnownRootsMap,
+  byPathDepth,
+  dedupeTopmostRoots,
+  findProjectRoot,
+  isWithin,
+  isWithinOrEqual,
+  mergeKnownRoots,
+  resolveKnownRoot,
+  segmentCount,
+  sortRootsBySpecificity,
+  walkProject,
+} from "./project-roots.ts";

package/node_modules/@mrclrchtr/supi-core/src/session.ts

@@ -0,0 +1,4 @@
+// supi-core session domain — session utilities and registries.
+
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
+export { getActiveBranchEntries } from "./session-utils.ts";

package/node_modules/@mrclrchtr/supi-core/src/settings-ui.ts

@@ -0,0 +1,2 @@
+// supi-core settings-ui domain — settings TUI components (imports pi-tui at runtime, heavy).
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";

package/node_modules/@mrclrchtr/supi-core/src/settings.ts

@@ -0,0 +1,9 @@
+// supi-core settings domain — settings registry (lightweight, type-only pi-tui import).
+
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
+export {
+  clearRegisteredSettings,
+  getRegisteredSettings,
+  registerSettings,
+} from "./settings/settings-registry.ts";

package/node_modules/@mrclrchtr/supi-core/src/substrate-types.ts

@@ -0,0 +1,11 @@
+/** 0-based position used by LSP and code-intelligence internally. */
+export interface CodePosition {
+  line: number;
+  character: number;
+}
+
+/** Normalized location — flat replacement for LSP's nested Location/range shape. */
+export interface CodeLocation {
+  uri: string;
+  range: { start: CodePosition; end: CodePosition };
+}

package/node_modules/@mrclrchtr/supi-core/src/types.ts

@@ -0,0 +1,2 @@
+// supi-core types domain — shared substrate types (zero dependencies, pure types).
+export type { CodeLocation, CodePosition } from "./substrate-types.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-claude-md",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "SuPi claude-md extension — automatic subdirectory context injection for pi",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.7.0"
+    "@mrclrchtr/supi-core": "1.8.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/skills/claude-md-improver/SKILL.md

@@ -41,6 +41,7 @@ Add rows for any additional categories visible in context.
 
 - **Root-level high risk** (already auto-delivered; do NOT recommend for root `./CLAUDE.md`):
   - Package/module inventories (from `supi-code-intelligence`)
+  - Package layout / project structure sections that just list packages with descriptions (from `supi-code-intelligence`)
   - Root directory trees and file counts (from `supi-code-intelligence`)
   - Dependency graphs from manifests (from `supi-code-intelligence`)
   - High-level architecture without project-specific reasoning (from `supi-code-intelligence`)
@@ -49,7 +50,7 @@ Add rows for any additional categories visible in context.
   - Subdirectory CLAUDE.md/AGENTS.md already injected by `supi-claude-md` during this session
 
 - **Low risk** (not auto-delivered; safe to recommend in CLAUDE.md at any scope):
-  - Commands and workflows
+  - Non-obvious commands and workflows (not routine build/test/lint — those are in package.json)
   - Gotchas and non-obvious patterns
   - Cross-package conventions not obvious from manifests
   - Curated "start here" guidance with ownership or boundary reasoning
@@ -108,7 +109,7 @@ For each CLAUDE.md file found in Phase 2, evaluate against quality criteria, inc
 
 | Criterion | Weight | Check |
 |-----------|--------|-------|
-| Commands/workflows documented | High | Are build/test/deploy commands present? |
+| Commands/workflows documented | High | Are non-obvious commands/workflows captured (not routine build/test)? |
 | Architecture clarity | High | Can PI understand the codebase structure? |
 | Non-obvious patterns | Medium | Are gotchas and quirks documented? |
 | Conciseness | Medium | No verbose explanations or obvious info? |
@@ -136,6 +137,9 @@ Format:
 - Files found: X
 - Average score: X/100
 - Files needing update: X
+- Potential token savings: ~X (removing redundant/auto-delivered content)
+
+**Auto-delivered content overlaps are never "minor" or "not worth the churn."** Content that duplicates what SuPi extensions auto-inject wastes tokens every session and MUST be flagged for removal. A single edit that saves ~200 tokens per session pays for itself within a few sessions.
 
 ### File-by-File Assessment
 
@@ -147,6 +151,7 @@ Format:
 - **Fully redundant (package-specific):** [sections already covered by baseline context — applies to that package's `CLAUDE.md`]
 - **Partially redundant:** [sections with overlap plus human-only value]
 - **Unique:** [sections that should stay]
+- **Estimated waste:** ~X tokens (characters ÷ 4) of existing content duplicate auto-delivered context — should be removed
 
 | Criterion | Score | Notes |
 |-----------|-------|-------|
@@ -161,6 +166,9 @@ Format:
 **Issues:**
 - [List specific problems]
 
+**Recommended removals (non-negotiable for auto-delivered content):**
+- [List what MUST be removed or compressed, with estimated token savings. Auto-delivered content is never "minor" or "not worth the churn" — it wastes tokens every session and MUST be removed.]
+
 **Recommended additions:**
 - [List what should be added]
 
@@ -170,24 +178,33 @@ Format:
 
 ### Phase 5: Targeted Updates
 
+**Core principle: every token must earn its place in the instruction file.** If content doesn't save future sessions more time than it costs to read, remove it. No instruction file should exceed 200 lines — above that, every line must fight for its place against removal.
+
 After outputting the quality report, ask user for confirmation before updating.
 
 **Update Guidelines (Critical):**
 
-1. **Propose targeted additions only** - Focus on genuinely useful info:
-   - Commands or workflows discovered during analysis
+1. **Remove or compress unnecessary content first** — Before adding anything, flag sections that MUST be removed or tightened. Never skip removals because of edit churn — a one-time edit that saves tokens every session pays for itself immediately.
+   - Routine command listings (`npm install`, `npm test`, `npm run build`) — remove; they're in package.json
+   - Package/module inventories that duplicate what `code_brief` auto-delivers — MUST be removed (these waste hundreds of tokens every session)
+   - Package layout / project structure sections that just list packages with descriptions — MUST be removed; `code_intelligence` delivers this. Architecture trees that restate what `code_map` or `code_intelligence` auto-deliver are never acceptable.
+   - Verbose explanations where a one-liner suffices — compress
+   - Stale or outdated commands, file references, or architecture descriptions — remove
+
+2. **Then propose targeted additions** — Add only genuinely useful, non-obvious info:
+   - Non-obvious commands or workflows discovered during analysis. Non-obvious means: gotcha flags (`--unsafe`, `--runInBand`), hook behaviors, ordering requirements, cross-tool workflows. Routine commands with scoped paths (`pnpm vitest run packages/<pkg>/path`) are still routine — they're equally discoverable from the file tree.
    - Gotchas or non-obvious patterns found in code
    - Package relationships that weren't clear
    - Testing approaches that work
    - Configuration quirks
 
-2. **Keep it minimal** - Avoid:
+3. **Keep it minimal** - Avoid:
    - Restating what's obvious from the code
    - Generic best practices already covered
    - One-off fixes unlikely to recur
    - Verbose explanations when a one-liner suffices
 
-3. **Show diffs** - For each change, show:
+4. **Show diffs** - For each change, show:
    - Which CLAUDE.md file to update
    - The specific addition (as a diff or quoted block)
    - Brief explanation of why this helps future sessions
@@ -197,15 +214,10 @@ After outputting the quality report, ask user for confirmation before updating.
 ```markdown
 ### Update: ./CLAUDE.md
 
-**Why:** Build command was missing, causing confusion about how to run the project.
+**Why:** The pre-push hook behavior wasn't documented, causing repeated confusion in CI.
 
 ```diff
-+ ## Quick Start
-+
-+ ```bash
-+ npm install
-+ npm run dev  # Start development server on port 3000
-+ ```
++ The pre-push hook runs `pnpm verify` — covers both lint and tests; don't run them separately.
 ```
 ```
 
@@ -219,19 +231,18 @@ See [references/templates.md](references/templates.md) for CLAUDE.md templates b
 
 ## Common Issues to Flag
 
-1. **Stale commands**: Build commands that no longer work
+1. **Stale commands**: Non-obvious commands or flags that no longer work
 2. **Missing dependencies**: Required tools not mentioned
 3. **Outdated architecture**: File structure that's changed
 4. **Missing environment setup**: Required env vars or config
-5. **Broken test commands**: Test scripts that have changed
-6. **Undocumented gotchas**: Non-obvious patterns not captured
+5. **Undocumented gotchas**: Non-obvious patterns not captured
 
 ## User Tips to Share
 
 When presenting recommendations, remind users:
 
 - **Keep it concise**: CLAUDE.md should be human-readable; dense is better than verbose
-- **Actionable commands**: All documented commands should be copy-paste ready
+- **Actionable commands**: All documented commands should be non-obvious and copy-paste ready; skip routine ones
 - **Use `.claude.local.md`**: For personal preferences not shared with team (add to `.gitignore`)
 - **Global defaults**: Put user-wide preferences in `~/.claude/CLAUDE.md`
 
@@ -239,16 +250,16 @@ When presenting recommendations, remind users:
 
 **Key principles:**
 - Concise and human-readable
-- Actionable commands that can be copy-pasted
+- Non-obvious commands and workflows (gotcha flags, ordering, hooks — not routine build/test)
 - Project-specific patterns, not generic advice
 - Non-obvious gotchas and warnings
 
 **Recommended sections** (use only what's relevant):
-- Commands (build, test, dev, lint)
+- Non-Obvious Commands & Workflows (gotcha flags, hook behaviors, ordering)
 - Architecture (directory structure)
 - Key Files (entry points, config)
 - Code Style (project conventions)
 - Environment (required vars, setup)
-- Testing (commands, patterns)
+- Testing (non-obvious patterns and conventions)
 - Gotchas (quirks, common mistakes)
 - Workflow (when to do what)

package/skills/claude-md-improver/references/quality-criteria.md

@@ -2,20 +2,20 @@
 
 ## Scoring Rubric
 
-### 1. Commands/Workflows (15 points)
+### 1. Non-Obvious Commands & Workflows (15 points)
 
-**15 points**: All essential commands documented with context
-- Build, test, lint, deploy commands present
-- Development workflow clear
-- Common operations documented
+**15 points**: Non-obvious commands and workflow patterns captured with context
+- Gotcha commands or required flags documented (e.g. `--unsafe`, `--runInBand`)
+- Hook/pre-push behaviors, ordering requirements, or cross-tool workflows captured
+- Routine install/build/test/lint commands are NOT counted toward this score
 
-**12 points**: Most commands present, some missing context
+**12 points**: Most non-obvious commands/workflows present, some missing context
 
-**8 points**: Basic commands only, no workflow
+**8 points**: Only routine commands listed, no non-obvious patterns
 
-**4 points**: Few commands, many missing
+**4 points**: Few or irrelevant commands
 
-**0 points**: No commands documented
+**0 points**: No commands or workflows documented
 
 ### 2. Architecture Clarity (15 points)
 
@@ -49,16 +49,19 @@
 
 ### 4. Conciseness (15 points)
 
-**15 points**: Dense, valuable content
-- No filler or obvious info
-- Each line adds value
-- No redundancy with code comments
+**Hard cap: no instruction file should exceed 200 lines.** Above 200 lines the score is capped at 5/15 regardless of content quality; above 300 lines the score is 0/15. Every line past 200 must fight for its place against removal.
 
-**10 points**: Mostly concise, some padding
+**15 points**: Every token earns its place — file is ≤200 lines
+- No filler, obvious info, or unnecessary content; every token saves more time than it costs to read
+- Each line adds value that isn't trivially discoverable elsewhere
+- No redundancy with code comments, package.json, or README
+- Routine commands already removed or never present
 
-**5 points**: Verbose in places
+**10 points**: Mostly concise, some padding — file is ≤200 lines
 
-**0 points**: Mostly filler or restates obvious code
+**5 points**: Over 200 lines, or verbose with significant padding
+
+**0 points**: Over 300 lines, or mostly filler / restates obvious code
 
 ### 5. Currency (15 points)
 
@@ -98,7 +101,7 @@ Score this criterion after a **context baseline review**: compare the CLAUDE.md
 
 **0 points**: Large sections are almost entirely duplicated generated context (module lists with descriptions, dense dependency tables, long root directory trees).
 
-**What is NOT overlap:** Gotchas specific to a package's behavior; cross-package patterns that aren't discoverable from manifests; commands and workflows; human-curated "Start Here" guidance with reasoning; concise structure notes that explain boundaries, ownership, initialization order, or important exceptions; and sections classified as **unique** during the baseline review.
+**What is NOT overlap:** Gotchas specific to a package's behavior; cross-package patterns that aren't discoverable from manifests; non-obvious commands and workflows (gotcha flags, hook behaviors, ordering requirements — not routine npm install/test/build); human-curated "Start Here" guidance with reasoning; concise structure notes that explain boundaries, ownership, initialization order, or important exceptions; and sections classified as **unique** during the baseline review.
 
 **What IS overlap:** Monorepo package tables where every row is `{name, description, path}`; root-level "Modules" or "Packages" sections with >5 entries; the **fully redundant** portion of a section during baseline review; root `## Project structure` / `## Architecture` trees that mostly restate folders, packages, or module layout already visible from `code_brief`; high-level architecture overviews that don't add relationships, gotchas, conventions, or exceptions beyond what's in `package.json`; and dependency graphs that could be generated from `pnpm-workspace.yaml`.