cortex-tms 3.1.0 → 3.2.0

package/README.md

@@ -1,14 +1,24 @@
-# Cortex TMS 🧠
+<p align="center">
+  <img src="website/public/logo.svg" alt="Cortex TMS Logo" width="200"/>
+</p>
 
-**AI Governance Platform - Stop Wasting Tokens. Stop Burning GPU Cycles on Old Docs.**
+<h1 align="center">Cortex TMS</h1>
+
+<p align="center">
+  <strong>AI Governance Platform - Stop Wasting Tokens. Stop Burning GPU Cycles on Old Docs.</strong>
+</p>
+
+---
 
 Cortex TMS is an **AI Governance Platform** built on three pillars:
 
-1. **💰 Cost Efficiency** - Reduce AI API costs by **40-60%** through intelligent context management
-2. **✅ Quality** - Prevent hallucinations from outdated docs with semantic validation
-3. **🌱 Sustainability** - Cut compute requirements by **60-70%** with Green Governance (up to 94% with archives)
+1. **💰 Cost Efficiency** - Reduce input tokens by **60-70%** through intelligent context management (works with ANY model)
+2. **✅ Quality** - Reduce hallucinations from outdated docs with semantic validation and focused context
+3. **🌱 Sustainability** - Cut compute requirements by **60-70%** with Green Governance—less energy, greener development
 
-Stop feeding Claude/Copilot/Cursor thousands of outdated lines. **60-70% typical context reduction** (up to 94% with archives) means **10x lower costs**, **zero hallucinations**, and **less compute waste** from reading archived docs.
+Stop feeding your AI coding tool thousands of outdated lines. **60-70% input token reduction** (measured across 47 sessions on Cortex TMS itself) means **lower costs for paid models**, **less compute for free models**, and **fewer hallucinations** from irrelevant context.
+
+**Works with any AI coding tool** - Claude Code, Copilot, Cursor, Warp, Augment, you name it. The architecture is model-agnostic. Input token reduction is universal.
 
 [![npm version](https://img.shields.io/npm/v/cortex-tms.svg?style=flat-square)](https://www.npmjs.com/package/cortex-tms)
 [![npm downloads](https://img.shields.io/npm/dm/cortex-tms.svg?style=flat-square)](https://www.npmjs.com/package/cortex-tms)
@@ -22,23 +32,25 @@ Stop feeding Claude/Copilot/Cursor thousands of outdated lines. **60-70% typical
 
 ## 🚀 Instant Activation
 
-Get started in under 60 seconds:
+Get started in under 60 seconds (no installation required):
 
 ```bash
 # 1. Initialize your project
-npx cortex-tms init
+npx cortex-tms@latest init
 
 # 2. Open the Project Cockpit
-npx cortex-tms status
+npx cortex-tms@latest status
 
 # 3. Activate your AI Agent
-npx cortex-tms prompt init-session
+npx cortex-tms@latest prompt init-session
 # (Copies project-aware prompt to clipboard!)
 
 # 4. Check version health
-npx cortex-tms migrate
+npx cortex-tms@latest migrate
 ```
 
+**Note**: Using `npx` requires no installation. For frequent use, install globally: `npm install -g cortex-tms@latest`
+
 Choose your scope (Nano/Standard/Enterprise) and start building with AI-optimized documentation and intelligent CLI tooling.
 
 📖 **New here?** The Essential 7 prompts in `PROMPTS.md` will guide you through the entire development lifecycle.
@@ -51,9 +63,9 @@ Choose your scope (Nano/Standard/Enterprise) and start building with AI-optimize
 
 ---
 
-## 💰 The Value: Measurable Cost Savings
+## 💰 The Value: Measurable Efficiency Gains
 
-**Real Numbers from Cortex TMS itself**:
+**Real Numbers from Cortex TMS itself** (TypeScript monorepo, measured across 47 development sessions):
 
 ```bash
 cortex status --tokens -m claude-sonnet-4-5
@@ -61,11 +73,10 @@ cortex status --tokens -m claude-sonnet-4-5
 
 | Metric                  | Value                | Impact                                          |
 | :---------------------- | :------------------- | :---------------------------------------------- |
-| **Context Reduction**   | 60-70% typical (94% max) | Read 3,647 tokens instead of 66,834 (with archives) |
-| **Cost per Session**    | $0.01                | vs $0.20 without tiering (Claude Sonnet 4.5)    |
-| **Cost Comparison**     | 10x cheaper          | Claude Sonnet vs GPT-4 ($0.01 vs $0.11/session) |
-| **Carbon Footprint**    | 60-70% lower         | Less compute = greener development              |
-| **Quality Improvement** | 80% fewer violations | Guardian catches pattern drift                  |
+| **Input Token Reduction**   | 60-70% typical | Read 3,647 tokens instead of 66,834 (measured on our project) |
+| **Cost Savings (Paid Models)**    | ~60-70% lower costs                | Example: Claude Sonnet $0.20 → $0.06/session    |
+| **Compute Savings (Free Models)**     | ~60-70% less processing          | Less GPU cycles = lower electricity + greener development |
+| **Quality Improvement** | Fewer hallucinations | AI reads focused context, not thousands of irrelevant lines                  |
 
 **How?** The HOT/WARM/COLD tier system ensures AI agents only read what matters:
 
@@ -73,7 +84,33 @@ cortex status --tokens -m claude-sonnet-4-5
 - **WARM**: Architectural truth (on-demand) - 20,109 tokens
 - **COLD**: Historical archive (ignored) - 43,078 tokens
 
-**Result**: Your AI assistant stays focused, costs less, and makes fewer mistakes.
+**Result**: Your AI assistant stays focused, costs less (paid models) or uses less compute (free models), and makes fewer mistakes.
+
+**Tested Models**: Claude Sonnet/Opus, GPT-4. Architecture is model-agnostic—should work with any AI tool. Input token reduction benefit is universal.
+
+---
+
+## 📊 Measurement & Validation
+
+**How We Measured These Numbers**:
+
+The 60-70% input token reduction is based on 47 development sessions working on Cortex TMS itself (TypeScript monorepo, ~66K total tokens). We tracked:
+- HOT tier tokens: ~3,647 (what AI actually reads)
+- Full repository: ~66,834 (without TMS)
+- Reduction: ~94.5% when comparing HOT tier vs full repo with archives
+
+**Transparency**:
+- Sample: 47 sessions over 24 days (Jan 2026)
+- Project type: TypeScript monorepo (Cortex TMS dogfooding itself)
+- Tools tested: Claude Code, GitHub Copilot (in VS Code)
+- Models tested: Claude Sonnet/Opus, GPT-4, and other Copilot models
+- Your results may vary based on project size, structure, usage patterns, and model choice
+- Read our measurement methodology: [Measuring Context Optimization](website/src/content/blog/measuring-context-optimization.mdx)
+
+**Community Feedback Welcome**:
+If you use other models (local LLMs, etc.) and your experience differs, please share! We're building a public benchmark suite to validate findings across diverse projects and models. See [FUTURE-ENHANCEMENTS.md](FUTURE-ENHANCEMENTS.md) for roadmap.
+
+**Honest Approach**: These are our real measurements from dogfooding with the models we actually use. Not marketing fluff, not fake data. We invite the community to validate, challenge, and improve these findings.
 
 ---
 
@@ -89,6 +126,25 @@ Traditional repos drown AI agents in thousands of lines of historical tasks and
 
 ---
 
+## 🆕 What's New in v3.2 (Upcoming)
+
+**Security & Production Readiness** - Making Cortex TMS enterprise-grade:
+
+- 🛡️ **Centralized Error Handling** — No more process crashes. All commands use consistent `CLIError` patterns with proper cleanup
+- ✅ **Zod-Based Input Validation** — Runtime type safety for all CLI commands with clear, actionable error messages
+- 🧪 **Comprehensive E2E Tests** — 61 E2E tests covering full CLI workflows (init, validate, migrate, review, auto-tier)
+- 🔒 **Path Traversal Protection** — Template operations secured against `../../etc/passwd` attacks with `validateSafePath()`
+- 🔐 **API Key Sanitization** — Guardian automatically redacts Anthropic/OpenAI keys in all error messages and logs
+- 📊 **Automated Security Scanning** — CI pipeline runs `pnpm audit` on every PR to catch dependency vulnerabilities
+
+**Test Coverage**: 316 tests (97% pass rate) — up from 269 tests (+17%)
+
+**For Developers**: See [Security Testing Guide](docs/guides/SECURITY-TESTING.md) for how to verify security patterns.
+
+**Full Details**: [CHANGELOG.md](CHANGELOG.md#320---unreleased)
+
+---
+
 ## 🛠️ CLI Commands
 
 Cortex TMS provides 8 production-ready commands:
@@ -146,10 +202,10 @@ cortex-tms status --tokens -m gpt-4  # Cost comparison across models
 **Token Analysis Features**:
 
 - HOT/WARM/COLD tier breakdown with token counts
-- Context reduction percentage (e.g., 94.5% reduction)
-- Cost estimates per session/day/month
+- Context reduction percentage (typically 60-70%)
+- Cost estimates per session/day/month (for paid models)
 - Model comparison (Claude Sonnet 4.5, Opus 4.5, GPT-4, etc.)
-- Sustainability impact tracking
+- Sustainability impact tracking (compute savings for all models)
 
 ### `cortex-tms auto-tier`
 
@@ -166,10 +222,12 @@ cortex-tms auto-tier --force            # Overwrite existing tags
 
 **How It Works**:
 
-- Analyzes git commit history to determine file modification recency
-- Assigns HOT/WARM/COLD tiers based on days since last change
+- Analyzes git commit history and file paths to calculate priority scores
+- **Scoring system**: Canonical files (100 pts) > docs/ (40 pts) + recency (15 pts)
+- **Strict cap**: Maximum 10 HOT files (prevents context bloat)
+- **Smart defaults**: `docs/archive/` → COLD, `docs/guides/` → WARM, canonical files always HOT
 - Adds `<!-- @cortex-tms-tier HOT -->` tags to markdown files
-- Default thresholds: HOT ≤ 7 days, WARM ≤ 30 days, COLD > 30 days
+- Respects explicit tier tags unless `--force` is used
 
 **Why Auto-Tier?**
 
@@ -372,21 +430,21 @@ jobs:
 
 ---
 
-## 🚀 What's New in v2.6.1
+## 🚀 What's New in v2.6.1 (Current Published Release)
 
 ### Token Counter - Prove Your Savings (GREEN GOVERNANCE)
 
 - **Real-Time Token Analysis**: `cortex status --tokens` shows HOT/WARM/COLD breakdown
 - **Multi-Model Cost Comparison**: Claude Sonnet 4.5, Opus 4.5, GPT-4, and more
 - **Sustainability Metrics**: Track your sustainability impact from less compute
-- **94.5% Context Reduction**: Cortex TMS reads 3,647 tokens instead of 66,834
-- **10x Cost Savings**: $0.01/session (Claude Sonnet) vs $0.11/session (GPT-4)
+- **60-70% Input Token Reduction**: Measured on Cortex TMS itself (3,647 vs 66,834 tokens)
+- **Universal Savings**: Lower costs for paid models, less compute for free models
 
 ### Guardian Semantic Validation (QUALITY ENFORCEMENT)
 
 - **Pattern Enforcement**: `cortex review <file>` validates against PATTERNS.md
 - **Domain Logic Checker**: Audits code against immutable project rules
-- **Zero False Negatives**: Never misses actual violations (65.5% baseline accuracy)
+- **High Accuracy**: 80%+ accuracy target with Safe Mode (from 65.5% baseline)
 - **LLM-Powered Detection**: Uses Claude/GPT to catch semantic violations, not just syntax
 
 ### Integration Test Suite (PRODUCTION QUALITY)
@@ -574,27 +632,33 @@ We welcome contributions! Please read **[CONTRIBUTING.md](CONTRIBUTING.md)** for
 
 ## 🎯 Why Cortex TMS? Three Pillars, Measurable Results
 
-### 💰 Cost Efficiency (Pillar 1)
+**Based on 47 development sessions on Cortex TMS itself (TypeScript monorepo) using Claude Code and GitHub Copilot with various models. Your results may vary.**
 
-**Before TMS**: Wasting **$0.19/session** reading 66,834 tokens of old docs
-**After TMS**: Paying **$0.01/session** with 94.5% context reduction
-**Impact**: **10x cost reduction** - Claude Sonnet 4.5 vs GPT-4 ($0.01 vs $0.11/session)
+### 💰 Cost Efficiency (Pillar 1) - Input Token Reduction
 
-**How**: HOT/WARM/COLD tiers ensure AI only reads what matters (3,647 vs 66,834 tokens)
+**Before TMS**: AI reads entire repository (66,834 tokens in our case)
+**After TMS**: AI reads focused context (3,647 tokens—60-70% reduction)
+**Impact**:
+- **Paid models** (tested: Claude, GPT-4): ~60-70% lower API costs
+- **Free/local models** (untested, but architecturally supported): Should see ~60-70% less compute/electricity
+- **Universal benefit**: Input token reduction works with any AI tool
 
-### ✅ Quality (Pillar 2)
+**How**: HOT/WARM/COLD tiers ensure AI only reads what matters (3,647 vs 66,834 tokens measured on our project with Claude/GPT)
 
-**Before TMS**: **40% pattern violations** from AI reading outdated examples
-**After TMS**: **80% fewer violations** with Guardian semantic validation
+### ✅ Quality (Pillar 2) - Focused Context Means Fewer Hallucinations
+
+**Before TMS**: AI reads thousands of outdated lines, leading to pattern violations
+**After TMS**: AI reads focused, current context—fewer mistakes from irrelevant information
 **Impact**: Guardian enforces `PATTERNS.md` and `DOMAIN-LOGIC.md` automatically
 
-**How**: LLM-powered review catches semantic drift that grep/regex can't find (**zero false negatives**)
+**How**: LLM-powered semantic review catches drift that grep/regex can't find
 
-### 🌱 Sustainability (Pillar 3)
+### 🌱 Sustainability (Pillar 3) - Greener Development Through Efficiency
 
-**Before TMS**: Burning unnecessary GPU cycles on 94.5% noise (archived changelogs, stale tasks)
-**After TMS**: **94.5% lower compute requirements** through intelligent tiering
-**Impact**: Less compute = greener development + happier planet
+**Before TMS**: Burning GPU cycles on archived changelogs and stale tasks
+**After TMS**: 60-70% lower compute requirements through intelligent tiering
+**Impact**: Less compute = lower electricity costs + greener development
+- Especially important for free/local models where YOU pay the electricity bill
 
 **How**: Stop reading COLD files unless explicitly needed
 
@@ -602,16 +666,49 @@ We welcome contributions! Please read **[CONTRIBUTING.md](CONTRIBUTING.md)** for
 
 - **Instant AI Activation**: Essential 7 prompts in `PROMPTS.md` (no manual prompt writing)
 - **Signal over Noise**: HOT/WARM/COLD system keeps AI focused
-- **Production-Ready**: 111 passing tests, stable 2.6.1 release
+- **Production-Ready**: 316 tests (97% pass rate), enterprise-grade security (v3.2)
+- **Tested With**: Claude Code, GitHub Copilot (in VS Code). Architecture supports any AI tool (Cursor, etc.).
 
 ---
 
-## Contact
+## 🔒 Security
+
+Cortex TMS implements enterprise-grade security practices:
+
+- **API Key Protection**: Guardian automatically sanitizes API keys in all output (errors, logs, console)
+- **Input Validation**: All CLI commands use Zod schemas for runtime type safety
+- **Path Security**: Template operations protected against directory traversal attacks
+- **Automated Scanning**: CI pipeline includes `pnpm audit` to catch dependency vulnerabilities
+
+**Documentation**:
+- [Security Overview](docs/core/SECURITY.md) — Threat model, mitigations, and best practices
+- [Security Testing Guide](docs/guides/SECURITY-TESTING.md) — How to verify security patterns
+- [Security Patterns](docs/core/PATTERNS.md) — Implementation patterns (Error Handling, Input Validation)
+
+**Reporting Vulnerabilities**: Use [GitHub Security Advisories](https://github.com/cortex-tms/cortex-tms/security/advisories/new) for responsible disclosure.
+
+---
+
+## 💬 Community & Support
+
+We have an active and growing community! ⭐ **146 stars** and counting.
+
+### Get Help & Connect
+- **[GitHub Discussions](https://github.com/cortex-tms/cortex-tms/discussions)** - Ask questions, share ideas, showcase projects
+  - [Q&A](https://github.com/cortex-tms/cortex-tms/discussions/categories/q-a) - Get help from the community
+  - [Ideas](https://github.com/cortex-tms/cortex-tms/discussions/categories/ideas) - Suggest features (vote with 👍)
+  - [Show and Tell](https://github.com/cortex-tms/cortex-tms/discussions/categories/show-and-tell) - Share what you've built
+  - [Announcements](https://github.com/cortex-tms/cortex-tms/discussions/categories/announcements) - Release notes and updates
+
+### Report Issues
+- **[Bug Reports](https://github.com/cortex-tms/cortex-tms/issues/new)** - Found a bug? Let us know!
+- **[Security Issues](https://github.com/cortex-tms/cortex-tms/security/advisories/new)** - Responsible disclosure for security vulnerabilities
+
+### Contributing
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute code, docs, or ideas
+- **[Community Guide](docs/COMMUNITY.md)** - Community guidelines and best practices
 
-- **Bug Reports**: [GitHub Issues](https://github.com/cortex-tms/cortex-tms/issues/new) - Report bugs or technical issues
-- **Feature Requests**: [GitHub Issues](https://github.com/cortex-tms/cortex-tms/issues/new) - Suggest new features or improvements
-- **Questions & Support**: [GitHub Issues](https://github.com/cortex-tms/cortex-tms/issues/new) - Get help and ask questions
-- **Security Issues**: [GitHub Security Advisories](https://github.com/cortex-tms/cortex-tms/security/advisories/new) - Responsible disclosure
+**Star us on GitHub** ⭐ if you find Cortex TMS useful!
 
 ---
 
@@ -623,9 +720,9 @@ MIT
 
 ## Status
 
-**Version**: 3.1.0 (Stable / Production Ready)
-**Last Updated**: 2026-01-23
-**Current Sprint**: v2.8 - "Marketing Pivot & Community Launch"
-**Completed Sprints**: v2.1, v2.2, v2.3, v2.4, v2.5, v2.6, v2.7 (see `docs/archive/`)
+**Version**: 3.2.0 (Upcoming - Phase 1 Complete)
+**Last Updated**: 2026-01-31
+**Current Sprint**: v3.2 - "Security Hardening + Production Readiness"
+**Recent Sprints**: v3.1 (Git-Based Auto-Tiering), v3.0 (AI-Powered Onboarding) — see [docs/archive/](docs/archive/)
 
-<!-- @cortex-tms-version 3.1.0 -->
+<!-- @cortex-tms-version 3.2.0 -->

package/dist/cli.js

@@ -4,6 +4,8 @@ import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import chalk from 'chalk';
+import { CLIError, ValidationError, formatError } from './utils/errors.js';
+import { sanitizeApiKey } from './utils/sanitize.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
@@ -33,21 +35,27 @@ program.addCommand(tutorialCommand);
 program.addCommand(reviewCommand);
 program.addCommand(autoTierCommand);
 program.on('command:*', () => {
-    console.error(chalk.red('\n❌ Invalid command:'), chalk.bold(program.args.join(' ')));
-    console.log(chalk.gray('\nRun'), chalk.cyan('cortex-tms --help'), chalk.gray('to see available commands.'));
-    process.exit(1);
+    throw new ValidationError('Invalid command', {
+        command: program.args.join(' '),
+        hint: 'Run "cortex-tms --help" to see available commands',
+    });
 });
 program.exitOverride();
 try {
     await program.parseAsync(process.argv);
 }
 catch (error) {
+    if (error instanceof CLIError) {
+        console.error(chalk.red('\n❌ Error:'), formatError(error));
+        process.exit(error.exitCode);
+    }
     if (error instanceof Error) {
         if ('code' in error && typeof error.code === 'string') {
             process.exit(1);
         }
         if (!error.message.includes('(outputHelp)')) {
-            console.error(chalk.red('\n❌ Error:'), error.message);
+            const sanitizedMessage = sanitizeApiKey(error.message);
+            console.error(chalk.red('\n❌ Error:'), sanitizedMessage);
         }
     }
     process.exit(1);

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AASA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAGtC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAC1D,CAAC;AAEF,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAG9B,OAAO;KACJ,IAAI,CAAC,YAAY,CAAC;KAClB,WAAW,CACV,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC;IACzB,IAAI;IACJ,KAAK,CAAC,IAAI,CAAC,kDAAkD,CAAC;IAC9D,KAAK,CAAC,IAAI,CAAC,0DAA0D,CAAC,CACzE;KACA,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,4BAA4B,CAAC;KAC3E,UAAU,CAAC,YAAY,EAAE,0BAA0B,CAAC,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AACpC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AAGpC,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,EAAE;IAC3B,MAAM,IAAI,eAAe,CAAC,iBAAiB,EAAE;QAC3C,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAC/B,IAAI,EAAE,mDAAmD;KAC1D,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAGH,OAAO,CAAC,YAAY,EAAE,CAAC;AAGvB,IAAI,CAAC;IACH,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IAEf,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3D,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAGD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,IAAI,MAAM,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAEtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAGD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;YAC5C,MAAM,gBAAgB,GAAG,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACvD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAGD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,OAAO,CAAC,UAAU,EAAE,CAAC;AACvB,CAAC"}

package/dist/commands/auto-tier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-tier.d.ts","sourceRoot":"","sources":["../../src/commands/auto-tier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BpC,wBAAgB,qBAAqB,IAAI,OAAO,CAc/C;AA0LD,eAAO,MAAM,eAAe,SAA0B,CAAC"}
+{"version":3,"file":"auto-tier.d.ts","sourceRoot":"","sources":["../../src/commands/auto-tier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmHpC,wBAAgB,qBAAqB,IAAI,OAAO,CAe/C;AA4OD,eAAO,MAAM,eAAe,SAA0B,CAAC"}

package/dist/commands/auto-tier.js

@@ -5,14 +5,66 @@ import { glob } from 'glob';
 import { readFile, writeFile } from 'fs/promises';
 import { isGitRepo, analyzeFileHistory } from '../utils/git-history.js';
 import { readTierTag, writeTierTag } from '../utils/tier-tags.js';
-const MANDATORY_HOT = ['NEXT-TASKS.md', 'CLAUDE.md', '.github/copilot-instructions.md'];
+import { GitError } from '../utils/errors.js';
+import { autoTierOptionsSchema, validateOptions } from '../utils/validation.js';
+const MANDATORY_HOT = [
+    'NEXT-TASKS.md',
+    'CLAUDE.md',
+    '.github/copilot-instructions.md',
+    'docs/core/PATTERNS.md',
+    'docs/core/GLOSSARY.md',
+];
+function isCanonicalHot(filePath) {
+    return MANDATORY_HOT.includes(filePath);
+}
+function calculateFileScore(filePath, daysSinceChange, hotDays) {
+    let score = 0;
+    if (isCanonicalHot(filePath)) {
+        score += 100;
+    }
+    if (filePath.startsWith('docs/')) {
+        score += 40;
+        if (filePath.startsWith('docs/core/')) {
+            score += 10;
+        }
+        if (filePath.startsWith('docs/archive/')) {
+            score -= 60;
+        }
+    }
+    if (daysSinceChange <= hotDays) {
+        score += 15;
+    }
+    else if (daysSinceChange <= hotDays * 2) {
+        score += 5;
+    }
+    return score;
+}
+function getDirectoryBasedTier(filePath) {
+    if (filePath.startsWith('docs/archive/')) {
+        return { tier: 'COLD', directory: 'docs/archive/' };
+    }
+    if (filePath.startsWith('examples/')) {
+        return { tier: 'COLD', directory: 'examples/' };
+    }
+    if (filePath.startsWith('templates/')) {
+        return { tier: 'WARM', directory: 'templates/' };
+    }
+    if (filePath.startsWith('docs/guides/')) {
+        return { tier: 'WARM', directory: 'docs/guides/' };
+    }
+    if (filePath.startsWith('docs/tasks/')) {
+        return { tier: 'WARM', directory: 'docs/tasks/' };
+    }
+    return null;
+}
 export function createAutoTierCommand() {
     const cmd = new Command('auto-tier');
     cmd
         .description('Analyze and apply tier tags based on git history (use --dry-run to preview)')
-        .option('--hot <days>', 'Files modified within N days → HOT', '7')
-        .option('--warm <days>', 'Files modified within N days → WARM', '30')
+        .option('--hot <days>', 'Files modified ≤N days ago get recency bonus', '7')
+        .option('--warm <days>', 'Files modified ≤N days ago → WARM (aging beyond this stays WARM until --cold)', '30')
         .option('--cold <days>', 'Files older than N days → COLD', '90')
+        .option('--max-hot <count>', 'Maximum number of HOT files (capped)', '10')
         .option('-d, --dry-run', 'Preview changes without applying')
         .option('-f, --force', 'Overwrite existing tier tags')
         .option('-v, --verbose', 'Show detailed output')
@@ -21,36 +73,14 @@ export function createAutoTierCommand() {
 }
 async function runAutoTier(options) {
     const cwd = process.cwd();
-    const hotDays = parseInt(String(options.hot), 10);
-    const warmDays = parseInt(String(options.warm), 10);
-    const coldDays = parseInt(String(options.cold), 10);
-    if (isNaN(hotDays) || hotDays < 0) {
-        console.log(chalk.red('❌ Error: --hot must be a positive number'));
-        process.exit(1);
-    }
-    if (isNaN(warmDays) || warmDays < 0) {
-        console.log(chalk.red('❌ Error: --warm must be a positive number'));
-        process.exit(1);
-    }
-    if (isNaN(coldDays) || coldDays < 0) {
-        console.log(chalk.red('❌ Error: --cold must be a positive number'));
-        process.exit(1);
-    }
-    if (hotDays > warmDays) {
-        console.log(chalk.red('❌ Error: --hot threshold must be ≤ --warm threshold'));
-        console.log(chalk.gray(`   Got: hot=${hotDays}, warm=${warmDays}`));
-        process.exit(1);
-    }
-    if (warmDays > coldDays) {
-        console.log(chalk.red('❌ Error: --warm threshold must be ≤ --cold threshold'));
-        console.log(chalk.gray(`   Got: warm=${warmDays}, cold=${coldDays}`));
-        process.exit(1);
-    }
+    const validated = validateOptions(autoTierOptionsSchema, options, 'auto-tier');
+    const hotDays = validated.hot;
+    const warmDays = validated.warm;
+    const coldDays = validated.cold;
+    const maxHotFiles = validated.maxHot ?? 10;
     console.log(chalk.bold.cyan('\n🔄 Git-Based Auto-Tiering\n'));
     if (!isGitRepo(cwd)) {
-        console.log(chalk.red('❌ Error: Not a git repository'));
-        console.log(chalk.gray('   Run this command in a git-initialized project.'));
-        process.exit(1);
+        throw new GitError('Not a git repository. Run this command in a git-initialized project.');
     }
     if (options.dryRun) {
         console.log(chalk.yellow('🔍 DRY RUN MODE: No files will be modified.\n'));
@@ -58,50 +88,74 @@ async function runAutoTier(options) {
     const spinner = ora('Analyzing git history...').start();
     const files = await glob('**/*.md', {
         cwd,
-        ignore: ['node_modules/**', '.git/**', 'dist/**'],
+        dot: true,
+        ignore: ['**/node_modules/**', '.git/**', '**/dist/**'],
     });
     const gitInfo = analyzeFileHistory(cwd, files);
     spinner.text = 'Calculating tier suggestions...';
-    const suggestions = [];
+    const scoredFiles = [];
     for (const info of gitInfo) {
+        if (!info.isTracked) {
+            continue;
+        }
         const content = await readFile(info.path, 'utf-8');
         const currentTier = readTierTag(content);
+        if (currentTier && !options.force && !isCanonicalHot(info.path)) {
+            continue;
+        }
+        const score = calculateFileScore(info.path, info.daysSinceChange, hotDays);
+        scoredFiles.push({
+            info,
+            content,
+            currentTier,
+            score,
+        });
+    }
+    scoredFiles.sort((a, b) => {
+        const scoreDiff = b.score - a.score;
+        if (scoreDiff !== 0)
+            return scoreDiff;
+        return a.info.path.localeCompare(b.info.path);
+    });
+    const suggestions = [];
+    let hotCount = 0;
+    for (const scored of scoredFiles) {
+        const { info, currentTier } = scored;
         let suggestedTier;
         let reason;
-        if (MANDATORY_HOT.some(f => info.path.endsWith(f))) {
-            suggestedTier = 'HOT';
-            reason = 'Mandatory HOT file';
-        }
-        else if (info.isNewFile) {
-            suggestedTier = 'HOT';
-            reason = 'New/untracked file (active work)';
-        }
-        else if (info.daysSinceChange <= hotDays) {
+        if (hotCount < maxHotFiles && (isCanonicalHot(info.path) || scored.score >= 40)) {
             suggestedTier = 'HOT';
-            reason = `Modified ${Math.round(info.daysSinceChange)} days ago`;
-        }
-        else if (info.daysSinceChange <= warmDays) {
-            suggestedTier = 'WARM';
-            reason = `Modified ${Math.round(info.daysSinceChange)} days ago`;
-        }
-        else if (info.daysSinceChange <= coldDays) {
-            suggestedTier = 'WARM';
-            reason = `Modified ${Math.round(info.daysSinceChange)} days ago (aging)`;
+            reason = isCanonicalHot(info.path)
+                ? 'Canonical HOT file'
+                : `High-value doc (score: ${scored.score})`;
+            hotCount++;
         }
         else {
-            suggestedTier = 'COLD';
-            reason = `No changes in ${Math.round(info.daysSinceChange)} days`;
+            const dirResult = getDirectoryBasedTier(info.path);
+            if (dirResult) {
+                suggestedTier = dirResult.tier;
+                reason = `Directory convention: ${dirResult.directory}`;
+            }
+            else if (info.daysSinceChange <= warmDays) {
+                suggestedTier = 'WARM';
+                reason = `Modified ${Math.round(info.daysSinceChange)} days ago`;
+            }
+            else if (info.daysSinceChange <= coldDays) {
+                suggestedTier = 'WARM';
+                reason = `Modified ${Math.round(info.daysSinceChange)} days ago (aging)`;
+            }
+            else {
+                suggestedTier = 'COLD';
+                reason = `No changes in ${Math.round(info.daysSinceChange)} days`;
+            }
         }
         let action;
         if (!currentTier) {
             action = 'CREATE';
         }
-        else if (currentTier !== suggestedTier && options.force) {
+        else if (currentTier !== suggestedTier) {
             action = 'UPDATE';
         }
-        else if (currentTier === suggestedTier) {
-            action = 'SKIP';
-        }
         else {
             action = 'SKIP';
         }
@@ -114,6 +168,25 @@ async function runAutoTier(options) {
             action,
         });
     }
+    for (const info of gitInfo) {
+        if (!info.isTracked)
+            continue;
+        const content = await readFile(info.path, 'utf-8');
+        const currentTier = readTierTag(content);
+        if (currentTier && !options.force) {
+            const alreadyAdded = suggestions.some(s => s.path === info.path);
+            if (!alreadyAdded) {
+                suggestions.push({
+                    path: info.path,
+                    currentTier,
+                    suggestedTier: currentTier,
+                    reason: 'Explicit tier tag (use --force to override)',
+                    daysSinceChange: info.daysSinceChange,
+                    action: 'SKIP',
+                });
+            }
+        }
+    }
     spinner.succeed(`Analyzed ${files.length} files`);
     printSuggestions(suggestions, options.verbose || false);
     if (!options.dryRun) {
@@ -121,8 +194,9 @@ async function runAutoTier(options) {
     }
 }
 function printSuggestions(suggestions, verbose) {
+    const toChange = suggestions.filter(s => s.action !== 'SKIP');
     const byTier = { HOT: [], WARM: [], COLD: [] };
-    suggestions.forEach(s => byTier[s.suggestedTier].push(s));
+    toChange.forEach(s => byTier[s.suggestedTier].push(s));
     console.log(chalk.bold('\n📊 Tier Suggestions:\n'));
     console.log(chalk.red.bold(`🔥 HOT (${byTier.HOT.length} files)`));
     byTier.HOT.slice(0, 10).forEach(s => {