cortex-tms 3.1.0 → 4.0.0

package/README.md

@@ -1,14 +1,16 @@
-# 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>
 
-Cortex TMS is an **AI Governance Platform** built on three pillars:
+<p align="center">
+  <strong>Documentation Governance for AI Coding Agents</strong>
+</p>
 
-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)
-
-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.
+<p align="center">
+  ⭐ 166+ GitHub Stars | Open source, community-driven
+</p>
 
 [![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)
@@ -16,106 +18,113 @@ Stop feeding Claude/Copilot/Cursor thousands of outdated lines. **60-70% typical
 [![node version](https://img.shields.io/node/v/cortex-tms.svg?style=flat-square)](https://nodejs.org)
 [![GitHub stars](https://img.shields.io/github/stars/cortex-tms/cortex-tms.svg?style=flat-square)](https://github.com/cortex-tms/cortex-tms/stargazers)
 
-**Current Status**: ✅ **Stable / Production Ready** | [NPM Package](https://www.npmjs.com/package/cortex-tms) | [GitHub Repository](https://github.com/cortex-tms/cortex-tms) | [Documentation](https://cortex-tms.org)
-
 ---
 
-## 🚀 Instant Activation
+## What is Cortex TMS?
 
-Get started in under 60 seconds:
-
-```bash
-# 1. Initialize your project
-npx cortex-tms init
+Cortex TMS scaffolds and validates governance documentation for AI coding agents. As AI models get more powerful and autonomous, they need clear, current governance docs to stay aligned with your project standards.
 
-# 2. Open the Project Cockpit
-npx cortex-tms status
+**The Challenge**: Modern AI agents (Claude Opus 4.6, GPT-4, etc.) handle large context windows and can work autonomously—but without governance, they drift from your standards, overengineer solutions, and write inconsistent code.
 
-# 3. Activate your AI Agent
-npx cortex-tms prompt init-session
-# (Copies project-aware prompt to clipboard!)
+**The Solution**: Cortex TMS provides:
+- 📋 **Documentation scaffolding** - Templates for PATTERNS.md, ARCHITECTURE.md, CLAUDE.md
+- ✅ **Staleness detection** - Detects when governance docs go stale relative to code changes (v4.0)
+- 🔍 **Structure validation** - Automated health checks in CI or locally
+- 📦 **Archive management** - Keep task lists focused and maintainable
 
-# 4. Check version health
-npx cortex-tms migrate
-```
+---
 
-Choose your scope (Nano/Standard/Enterprise) and start building with AI-optimized documentation and intelligent CLI tooling.
+## Three Pillars
 
-📖 **New here?** The Essential 7 prompts in `PROMPTS.md` will guide you through the entire development lifecycle.
+### 1. 📋 Consistency - Document Your Standards
 
-## 🎬 See It In Action
+Scaffold governance docs that AI agents actually read:
+- `PATTERNS.md` - Code patterns and conventions
+- `CLAUDE.md` - Agent workflow rules (git protocol, scope discipline, human approval gates)
+- `ARCHITECTURE.md` - System design and tech stack
+- `DOMAIN-LOGIC.md` - Business rules and constraints
 
-![Cortex TMS Demo](assets/demo.gif)
+**Result**: AI writes code that follows YOUR patterns, not random conventions from its training data.
 
-**Watch** the `cortex status` dashboard and `cortex migrate` workflow in action. See how Cortex TMS provides real-time project health metrics and intelligent version management.
+### 2. 🔍 Freshness - Detect Staleness
 
----
+New in v4.0: Git-based staleness detection catches when docs go stale:
 
-## 💰 The Value: Measurable Cost Savings
+```bash
+cortex-tms validate
 
-**Real Numbers from Cortex TMS itself**:
+⚠️  Doc Staleness
+    PATTERNS.md may be outdated
+    Doc is 45 days older than code with 12 meaningful commits
+    Code: 2026-02-20
+    Doc:  2026-01-06
 
-```bash
-cortex status --tokens -m claude-sonnet-4-5
+    Review docs/core/PATTERNS.md to ensure it reflects current codebase
 ```
 
-| 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                  |
+**How it works**: Compares doc modification dates vs code commit activity. Flags stale docs before they mislead AI agents.
 
-**How?** The HOT/WARM/COLD tier system ensures AI agents only read what matters:
+**Note**: Staleness v1 uses git timestamps (temporal comparison only). Cannot detect semantic misalignment. Future versions will add semantic analysis.
 
-- **HOT**: Current sprint (always read) - 3,647 tokens
-- **WARM**: Architectural truth (on-demand) - 20,109 tokens
-- **COLD**: Historical archive (ignored) - 43,078 tokens
+### 3. 🛡️ Safety - Human Oversight
 
-**Result**: Your AI assistant stays focused, costs less, and makes fewer mistakes.
+`CLAUDE.md` governance rules require human approval for critical operations:
+- Git commits/pushes require approval
+- Scope discipline prevents overengineering
+- Pattern adherence enforced through validation
+
+**Result**: AI agents stay powerful but don't run wild.
 
 ---
 
-## 🎯 The Philosophy: Signal over Noise
+## What Cortex Does (and Doesn't Do)
+
+### ✅ What Cortex Does
 
-Traditional repos drown AI agents in thousands of lines of historical tasks and stale documentation. **Cortex TMS** forces agents into a "Tiered" approach:
+- **Scaffolds governance docs** - Templates for common project documentation
+- **Validates doc health** - Checks structure, freshness, completeness
+- **Detects staleness** - Flags when docs are outdated relative to code (v4.0)
+- **Enforces size limits** - Keeps docs focused and scannable
+- **Archives completed tasks** - Maintains clean NEXT-TASKS.md
+- **Works in CI/CD** - GitHub Actions validation templates included
 
-1. **HOT (Active)**: `NEXT-TASKS.md`, `PROMPTS.md` — What we are doing _now_ and how to ask the AI for help.
-2. **WARM (Truth)**: `docs/core/` — The project's "Laws" (Architecture, Patterns, Domain Logic).
-3. **COLD (History)**: `docs/archive/` — Historical changelogs (Ignore unless asked).
+### ❌ What Cortex Does NOT Do
 
-**Why this works**: AI agents have limited context windows. Reading everything is wasteful. The tier system maximizes signal, minimizes noise.
+- **Not a token optimizer** - Modern models (200K+ contexts) make this less relevant
+- **Not code enforcement** - Validates DOCUMENTATION health, not code directly
+- **Not a replacement for code review** - Complements human review, doesn't replace it
+- **Not semantic analysis (yet)** - Staleness v1 uses timestamps, not AI-powered diff analysis
 
 ---
 
-## 🛠️ CLI Commands
+## Quick Start
 
-Cortex TMS provides 8 production-ready commands:
+```bash
+# Initialize governance docs in your project
+npx cortex-tms@latest init
 
-### `cortex-tms tutorial`
+# Validate doc health (including staleness detection)
+npx cortex-tms@latest validate
 
-Interactive walkthrough teaching the "Cortex Way" - perfect for first-time users.
+# Strict mode (warnings = errors, for CI)
+npx cortex-tms@latest validate --strict
 
-```bash
-cortex-tms tutorial  # Start the guided tour
-```
-
-**What You'll Learn**:
+# Check project status
+npx cortex-tms@latest status
 
-- Project Dashboard: Using `status` to see your cockpit
-- AI Activation: Using `prompt` to activate project-aware AI agents
-- Zero-Drift Governance: Automated version sync with `docs:sync`
-- Health Checks: Understanding `validate` and the Archive Protocol
-- Safe Migration: Fearless template upgrades with backup/rollback
+# Archive completed tasks
+npx cortex-tms@latest archive --dry-run
+```
 
-**Navigation**: Use arrow keys and Enter to progress, select Exit to quit anytime
+**Installation**: No installation required with `npx`. For frequent use: `npm install -g cortex-tms@latest`
 
 ---
 
+## CLI Commands
+
 ### `cortex-tms init`
 
-Initialize TMS structure in your project with interactive scope selection.
+Scaffold TMS documentation structure with interactive scope selection.
 
 ```bash
 cortex-tms init                    # Interactive mode
@@ -125,228 +134,89 @@ cortex-tms init --dry-run          # Preview changes
 
 ### `cortex-tms validate`
 
-Verify your project's TMS health and auto-fix common issues.
+Verify project TMS health with automated checks.
 
 ```bash
 cortex-tms validate         # Check project health
 cortex-tms validate --fix   # Auto-repair missing files
-cortex-tms validate --strict # Strict mode with no warnings
+cortex-tms validate --strict # Strict mode (warnings = errors)
 ```
 
+**What it checks:**
+- ✅ Mandatory files exist (NEXT-TASKS.md, CLAUDE.md, copilot-instructions.md)
+- ✅ File size limits (Rule 4: HOT files < 200 lines)
+- ✅ Placeholder completion (no `[Project Name]` markers left)
+- ✅ Archive status (completed tasks should be archived)
+- ✅ **Doc staleness** (NEW in v4.0) - governance docs current with code
+
 ### `cortex-tms status`
 
-Project cockpit with health dashboard, sprint progress, and token analysis.
+Project cockpit with health dashboard and sprint progress.
 
 ```bash
-cortex-tms status                    # Visual dashboard with progress bars
-cortex-tms status --tokens           # Token usage analysis (HOT/WARM/COLD)
-cortex-tms status --tokens -m gpt-4  # Cost comparison across models
+cortex-tms status  # Visual dashboard with progress bars
 ```
 
-**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
-- Model comparison (Claude Sonnet 4.5, Opus 4.5, GPT-4, etc.)
-- Sustainability impact tracking
+Shows:
+- Project identity (name, scope, TMS version)
+- Health status (validation checks passed/failed)
+- Sprint progress (current tasks, completion %)
+- Backlog size (future enhancements)
 
-### `cortex-tms auto-tier`
+### `cortex-tms archive`
 
-Git-based automatic tier assignment - reduce manual tier management using file recency as a relevance signal.
+Archive completed tasks and old content.
 
 ```bash
-cortex-tms auto-tier                    # Apply tier tags based on git history
-cortex-tms auto-tier --dry-run          # Preview tier suggestions
-cortex-tms auto-tier --hot 14 --warm 60 # Custom thresholds
-cortex-tms auto-tier --force            # Overwrite existing tags
+cortex-tms archive           # Archive completed tasks
+cortex-tms archive --dry-run # Preview what would be archived
 ```
 
-**Community-requested feature**: Built in response to feedback from Reddit users [Illustrious-Report96](https://www.reddit.com/user/Illustrious-Report96/), [pbalIII](https://www.reddit.com/user/pbalIII/), and [durable-racoon](https://www.reddit.com/user/durable-racoon/) who identified manual tier management as a scalability bottleneck and suggested using git history to determine file "heat".
-
-**How It Works**:
+Archives completed tasks from NEXT-TASKS.md to `docs/archive/` with timestamp.
 
-- Analyzes git commit history to determine file modification recency
-- Assigns HOT/WARM/COLD tiers based on days since last change
-- Adds `<!-- @cortex-tms-tier HOT -->` tags to markdown files
-- Default thresholds: HOT ≤ 7 days, WARM ≤ 30 days, COLD > 30 days
-
-**Why Auto-Tier?**
-
-- **Automates tier management**: No more manual tier decisions
-- **Objective signal**: Git history provides measurable recency data
-- **Aligns with "Lost in the Middle" research**: Recent files (likely relevant) placed at context beginning
-- **Adapts to workflow**: Tiers stay current as project evolves
+**Note**: `cortex-tms auto-tier` is deprecated—use `archive` instead.
 
 ### `cortex-tms migrate`
 
-Intelligent version management—detect outdated templates and automatically upgrade with safety backups.
+Intelligent version management—detect outdated templates and upgrade safely.
 
 ```bash
 cortex-tms migrate                    # Analyze version status
-cortex-tms migrate --apply            # Auto-upgrade OUTDATED files (creates backup)
-cortex-tms migrate --apply --force    # Upgrade ALL files including customized
-cortex-tms migrate --rollback         # Restore from backup (interactive selection)
-cortex-tms migrate --dry-run          # Preview migration plan
+cortex-tms migrate --apply            # Auto-upgrade OUTDATED files
+cortex-tms migrate --rollback         # Restore from backup
 ```
 
-**Status Categories**:
-
-- `LATEST`: Already on current version
-- `OUTDATED`: Safe to auto-upgrade (matches old template)
-- `CUSTOMIZED`: Manual review needed (has user changes)
-- `MISSING`: Optional file not installed
-
-**Safety Features**:
-
-- Automatic backups in `.cortex/backups/` before any changes
-- Timestamped snapshots with manifest files
-- One-click rollback with interactive backup selection
-- Confirmation prompts prevent accidental overwrites
-
 ### `cortex-tms prompt`
 
 Access project-aware AI prompts from the Essential 7 library.
 
 ```bash
 cortex-tms prompt              # Interactive selection
-cortex-tms prompt init-session # Direct access (auto-copies to clipboard!)
-cortex-tms prompt --list       # Browse all prompts
+cortex-tms prompt init-session # Auto-copies to clipboard
 ```
 
-**The Essential 7**:
-
-- `init-session` - Start your AI session with context
-- `feature` - Implement new features with architectural anchors
-- `debug` - Troubleshoot with known issues lookup
-- `review` - Code review against project patterns
-- `refactor` - Structural improvements
-- `decision` - Create Architecture Decision Records
-- `finish` - Execute maintenance protocol
-
 ### `cortex-tms review` 🛡️
 
-**Guardian**: AI-powered semantic validation against project patterns and domain logic.
+Guardian: AI-powered semantic validation against project patterns.
 
 ```bash
-cortex-tms review src/index.ts              # Validate file against PATTERNS.md
-cortex-tms review src/index.ts --safe       # Safe Mode: only high-confidence violations (≥70%)
-cortex-tms review src/index.ts --output-json  # Raw JSON output (for Agent Skills/CI/CD)
-cortex-tms review src/index.ts --provider openai  # Use OpenAI instead of Anthropic
-cortex-tms review src/index.ts --model gpt-4      # Specify model
-```
-
-**What Guardian Does**:
-
-- Analyzes code against `PATTERNS.md` (canonical examples, do/don't patterns)
-- Validates against `DOMAIN-LOGIC.md` (immutable project rules)
-- Uses LLM to catch **semantic violations**, not just syntax errors
-- Reports violations with specific pattern references
-
-**Why Guardian?**
-
-- **Structured Output**: JSON-based violation detection (80%+ accuracy target, from 65.5% baseline)
-- **Safe Mode**: `--safe` flag filters to high-confidence violations only (≥70%), reducing false positive noise
-- **Semantic Understanding**: Catches violations grep/regex can't find
-- **Pattern Enforcement**: Stops drift from architectural decisions
-- **BYOK (Bring Your Own Key)**: Uses your OpenAI or Anthropic API key
-- **Reliable Parsing**: Deterministic JSON eliminates keyword collision false positives
-
-**Example Output**:
-
+cortex-tms review src/index.ts              # Validate against PATTERNS.md
+cortex-tms review src/index.ts --safe       # High-confidence violations only
 ```
-🛡️  Guardian Code Review
-
-✅ Analysis Complete
-
-❌ **Major Violations**
-
-Code violates Pattern 1: Placeholder Syntax
-
-## Violations
-
-1. ❌ **Pattern 1: Placeholder Syntax**
-   📍 Line: 45
-   ❗ Issue: Using {braces} instead of [brackets] for placeholders
-   💡 Fix: Replace {project-name} with [project-name]
 
-## Positive Observations
-
-✅ Consistent indentation and formatting
-✅ Good use of TypeScript strict types
-```
-
----
-
-## 🔄 CI/CD Integration
-
-### Reusable GitHub Action
-
-Validate your TMS documentation in GitHub Actions workflows without installing the CLI locally.
-
-**Basic Usage** (in your `.github/workflows/tms-validate.yml`):
-
-```yaml
-name: TMS Validation
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  validate:
-    uses: cortex-tms/cortex-tms/.github/workflows/validate-reusable.yml@main
-```
-
-**With Custom Configuration**:
-
-```yaml
-jobs:
-  validate:
-    uses: cortex-tms/cortex-tms/.github/workflows/validate-reusable.yml@main
-    with:
-      strict: true                    # Enable strict mode (default: true)
-      scope: 'standard'               # Validation scope (default: auto-detect)
-      ignore-files: 'README.md'       # Comma-separated files to ignore
-      cortex-version: 'latest'        # Cortex TMS version (default: latest)
-      node-version: '20'              # Node.js version (default: 20)
-```
-
-**Available Inputs**:
-
-| Input | Description | Default |
-|:------|:------------|:--------|
-| `strict` | Enable strict validation mode (fails on warnings) | `true` |
-| `scope` | Validation scope (nano/standard/enterprise/auto-detect) | `auto-detect` |
-| `ignore-files` | Comma-separated list of files to ignore | `''` |
-| `cortex-version` | Cortex TMS version to install (e.g., "latest", "2.7.0") | `latest` |
-| `node-version` | Node.js version to use | `20` |
+### `cortex-tms tutorial`
 
-**Example with Multiple Ignored Files**:
+Interactive walkthrough teaching the Cortex Way.
 
-```yaml
-jobs:
-  validate:
-    uses: cortex-tms/cortex-tms/.github/workflows/validate-reusable.yml@main
-    with:
-      strict: false
-      ignore-files: 'README.md,CHANGELOG.md,docs/archive/*'
+```bash
+cortex-tms tutorial  # 5-lesson guided tour (~15 minutes)
 ```
 
-**Benefits**:
-
-- ✅ Zero-friction adoption (no local installation required)
-- ✅ Validates PRs automatically
-- ✅ Consistent enforcement across team
-- ✅ Works with any project using Cortex TMS
-
 ---
 
-## 📂 Documentation Structure
+## Documentation Structure
 
-| Folder / File                     | Purpose                                | AI Context Tier           |
+| Folder / File                     | Purpose                                | Tier                      |
 | :-------------------------------- | :------------------------------------- | :------------------------ |
 | `NEXT-TASKS.md`                   | Active sprint and current focus        | **HOT** (Always Read)     |
 | `PROMPTS.md`                      | AI interaction templates (Essential 7) | **HOT** (Always Read)     |
@@ -359,273 +229,209 @@ jobs:
 | `docs/core/GIT-STANDARDS.md`      | Git & PM conventions                   | **WARM** (Read on Demand) |
 | `docs/core/DECISIONS.md`          | Architecture Decision Records          | **WARM** (Read on Demand) |
 | `docs/core/GLOSSARY.md`           | Project terminology                    | **WARM** (Read on Demand) |
-| `docs/core/SCHEMA.md`             | Data models (optional)                 | **WARM** (Read on Demand) |
-| `docs/core/TROUBLESHOOTING.md`    | Framework gotchas (optional)           | **WARM** (Read on Demand) |
 | `docs/archive/`                   | Historical changelogs                  | **COLD** (Ignore)         |
 
-**Context Budget Limits**: To keep HOT files efficient:
-
-- `NEXT-TASKS.md`: Stay under **200 lines** (archive completed sprints to `docs/archive/`)
-- `.github/copilot-instructions.md`: Stay under **100 lines** (critical rules only)
-
-**Archive Trigger**: When a sprint completes, move tasks from `NEXT-TASKS.md` to `docs/archive/sprint-vX.X-YYYY-MM.md`.
+**HOT/WARM/COLD System**: Organizes docs by access frequency (not token optimization). Helps AI find what's relevant for each task.
 
 ---
 
-## 🚀 What's New in v2.6.1
-
-### 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)
-
-### 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)
-- **LLM-Powered Detection**: Uses Claude/GPT to catch semantic violations, not just syntax
-
-### Integration Test Suite (PRODUCTION QUALITY)
-
-- **111 Passing Tests**: 96 unit + 15 integration tests
-- **End-to-End Workflows**: Validates command interactions work correctly
-- **Error Recovery Testing**: Ensures rollback and fix workflows function
-- **CI/CD Ready**: ~8.5s execution time, zero flakiness
-
-### Error Handling Refactor (DEVELOPER EXPERIENCE)
+## Staleness Detection Configuration
+
+Configure staleness thresholds in `.cortexrc`:
+
+```json
+{
+  "version": "4.0.0",
+  "scope": "standard",
+  "staleness": {
+    "enabled": true,
+    "thresholdDays": 30,
+    "minCommits": 3,
+    "docs": {
+      "docs/core/PATTERNS.md": ["src/"],
+      "docs/core/ARCHITECTURE.md": ["src/", "infrastructure/"],
+      "docs/core/DOMAIN-LOGIC.md": ["src/"]
+    }
+  }
+}
+```
 
-- **Clean Exit Management**: Removed 17 `process.exit()` calls from command files
-- **Better Testability**: Commands throw errors instead of forcing exits
-- **Centralized Error Handler**: Commander.js `exitOverride()` for consistent behavior
+**How it works**:
+- Compares doc last modified date vs code commit activity
+- Flags stale if: `daysSinceDocUpdate > thresholdDays AND meaningfulCommits >= minCommits`
+- Excludes merge commits, test-only changes, lockfile-only changes
 
-### What's in v2.6.1 and Earlier
+**Limitations (v1)**:
+- Temporal comparison only (git timestamps)
+- Cannot detect semantic misalignment
+- Requires full git history (not shallow clones)
 
-- **Interactive Tutorial**: 5-lesson guided walkthrough (<15 minutes)
-- **Safe-Fail Migration**: Automatic backups with one-click rollback
-- **Zero-Drift Governance**: Automated version sync with CI Guardian
-- **Self-Healing Validation**: `--fix` flag auto-repairs common issues
-- **Migration Auditor**: Version tracking and customization detection
-- **Prompt Engine**: Essential 7 library with clipboard integration
+**CI Setup**: Ensure `fetch-depth: 0` in GitHub Actions to enable staleness detection.
 
 ---
 
-## 🤖 How to Work with AI Agents
+## CI/CD Integration
 
-This repo is a **"Machine-Legible Project Constitution."** To get the best results:
+Add to `.github/workflows/validate.yml`:
 
-### 1. The Context Trigger
-
-```bash
-cortex-tms prompt init-session
-# Copies: "Review NEXT-TASKS.md, docs/core/ARCHITECTURE.md, and CLAUDE.md.
-#          Summarize current priorities and propose a step-by-step plan..."
-```
+```yaml
+name: Cortex TMS Validation
 
-### 2. Pattern Enforcement
+on: [push, pull_request]
 
-```bash
-cortex-tms prompt review
-# Copies: "Review the current changes against PATTERNS.md.
-#          Flag any violations and suggest specific fixes."
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for staleness detection
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Validate TMS Health
+        run: npx cortex-tms@latest validate --strict
 ```
 
-### 3. Truth Anchoring
-
-If the AI hallucinates logic:
-
-> _"Your calculation is wrong. Refer to the rules in docs/core/DOMAIN-LOGIC.md."_
-
-### 4. Check Current Sprint
-
-```bash
-cortex-tms status  # Visual dashboard with current tasks
-```
+**Strict mode**: Warnings become errors, failing the build if:
+- Governance docs are stale
+- File size limits exceeded
+- Mandatory files missing
+- Placeholders not replaced
 
 ---
 
-## 📋 Development Roadmap
+## What's New in v4.0
 
-**Completed Phases** (All ✅):
+**🎯 Strategic Repositioning**: Quality governance over token optimization
 
-- [x] **Phase 1**: Dogfood the System - Applied TMS to Cortex itself
-- [x] **Phase 2**: Complete Template Library - All templates built and validated
-- [x] **Phase 3**: Build Example App - Gold Standard Next.js 15 Todo App
-- [x] **Phase 4**: Create CLI Tool - Full-featured CLI with 6 commands
-- [x] **Phase 5**: Documentation & Guides - Status dashboard, snippets, validation
-- [x] **Phase 6**: Publish & Scale - npm package + GitHub releases
+**Context**: Modern AI models (GPT-4, Claude Opus 4.6) now handle large contexts (200K+ tokens). The bottleneck shifted from "can AI see enough?" to "will AI stay aligned with project standards?"
 
-**Current Version**: v2.6.1 "Guardian & Green Governance" ✅
+### New Features
 
-- ✅ Token Counter with real-time cost analysis
-- ✅ Guardian semantic validation (Pattern + Domain Logic enforcement)
-- ✅ 111 passing tests (96 unit + 15 integration)
-- ✅ Error handling refactor for better testability
-- ✅ Multi-model cost comparison (Claude, GPT-4)
+**Staleness Detection** (v4.0):
+- ✅ Git-based freshness checks for governance docs
+- ✅ Configurable thresholds (days + commit count)
+- ✅ Per-doc watch directories
+- ✅ Exclude merges, test-only, lockfile-only commits
+- ✅ CI-ready (with `fetch-depth: 0`)
 
-**Next Phase (v3.0)**: Development & Refinement
+**Archive Command**:
+- ✅ `cortex-tms archive` - Archive completed tasks
+- ✅ Replaces deprecated `auto-tier` command
+- ✅ Dry-run mode for previewing changes
 
-- Website performance optimization
-- Guardian enhancements and reliability improvements
-- Migration experience improvements
-- Advanced token analytics
+**Simplified Status**:
+- ✅ Removed `--tokens` flag (streamlined to governance focus)
+- ✅ Shows: project health, sprint progress, backlog
 
-See `NEXT-TASKS.md` for current sprint details and `CHANGELOG.md` for full version history.
+### Breaking Changes
 
----
-
-## 🏗️ Project Structure
-
-```
-cortex-tms/
-├── NEXT-TASKS.md              # HOT: Current sprint
-├── PROMPTS.md                 # HOT: AI interaction templates
-├── FUTURE-ENHANCEMENTS.md     # PLANNING: Backlog
-├── CLAUDE.md                  # HOT: Workflow config
-├── README.md                  # This file
-├── .github/
-│   └── copilot-instructions.md # HOT: AI guardrails
-├── bin/                       # CLI executable
-├── src/                       # CLI source code
-│   ├── commands/              # CLI commands (init, validate, status, migrate, prompt, tutorial)
-│   ├── utils/                 # Template processing, validation, prompt parsing, backup
-│   └── types/                 # TypeScript definitions
-├── templates/                 # User-facing boilerplate
-│   ├── NEXT-TASKS.md
-│   ├── PROMPTS.md            # Essential 7 prompt library
-│   ├── CLAUDE.md
-│   ├── .github/
-│   │   └── copilot-instructions.md
-│   ├── vscode/
-│   │   └── tms.code-snippets # VS Code productivity snippets
-│   └── docs/
-│       ├── core/
-│       │   ├── ARCHITECTURE.md
-│       │   ├── PATTERNS.md
-│       │   ├── DOMAIN-LOGIC.md
-│       │   ├── GIT-STANDARDS.md
-│       │   ├── DECISIONS.md
-│       │   ├── GLOSSARY.md
-│       │   ├── SCHEMA.md
-│       │   └── TROUBLESHOOTING.md
-│       └── archive/
-│           └── v1.0-CHANGELOG.md
-├── docs/                      # Cortex TMS project documentation
-│   ├── core/
-│   └── archive/
-└── examples/                  # Reference implementations
-    └── todo-app/             # ✅ Gold Standard Next.js 15 App
-```
-
----
+**Removed**:
+- ❌ `cortex-tms status --tokens` flag
+- ❌ Token counting and cost analysis features
 
-## 🧪 Validation: Dogfooding
+**Deprecated**:
+- ⚠️ `cortex-tms auto-tier` → Use `cortex-tms archive` (still works with warning)
 
-**This repository uses TMS to build itself.**
+**Migration**:
+- Status command: Use `cortex-tms status` (no flags needed)
+- Archive tasks: Use `cortex-tms archive` instead of `auto-tier`
 
-- Cortex's own `NEXT-TASKS.md` tracks Cortex development
-- Cortex's own `docs/core/PATTERNS.md` documents template patterns
-- Cortex's own `PROMPTS.md` guides AI collaboration on Cortex
-
-**Validation Test**: "Can an AI agent working on Cortex find what it needs in < 3 file reads?" ✅
+See [CHANGELOG.md](CHANGELOG.md) for full version history.
 
 ---
 
-## 📚 Key Documentation
+## When to Use Cortex TMS
 
-- **For AI Agents**: Read `.github/copilot-instructions.md` and `PROMPTS.md` first
-- **For Developers**: Read `docs/core/ARCHITECTURE.md` for system design
-- **For Contributors**: Read `docs/core/PATTERNS.md` for template patterns
-- **For Understanding**: Read `docs/core/DOMAIN-LOGIC.md` for TMS principles
+### ✅ Good Fit
 
----
+- **Multi-file projects** - Complex codebases with established patterns
+- **Team projects** - Multiple developers + AI agents need consistency
+- **Long-running projects** - Documentation drift is a real risk
+- **AI-heavy workflows** - Using Claude Code, Cursor, Copilot extensively
+- **Quality-focused** - You value consistent code over speed
 
-## 🤝 Contributing
+### ⚠️ Maybe Not
 
-We welcome contributions! Please read **[CONTRIBUTING.md](CONTRIBUTING.md)** for detailed guidelines on:
-- How to submit bug reports and feature requests
-- Development setup and workflow
-- Pull request process and quality standards
-- Code style and testing requirements
-- Areas where we need help
+- **Single-file projects** - Overhead may outweigh benefits
+- **Throwaway prototypes** - Documentation governance not worth setup time
+- **Solo dev, simple project** - Mental model may be sufficient
+- **Pure exploration** - Constraints may slow discovery
 
-**Quick Start for Contributors**:
-1. Read [CONTRIBUTING.md](CONTRIBUTING.md) - **Required for all contributions**
-2. Check [open issues](https://github.com/cortex-tms/cortex-tms/issues) for `good-first-issue` labels
-3. For significant changes, open an issue for discussion **before** coding
-4. Follow patterns in `docs/core/PATTERNS.md`
-5. Ensure tests pass: `npm test`
-6. Submit PR with clear description and linked issue
+**Start simple**: Use `--scope nano` for minimal setup, expand as needed.
 
 ---
 
-## 📖 Learn More
+## Developer Experience
 
-- **Release Notes**: See `CHANGELOG.md` for version history
-- **Architecture**: See `docs/core/ARCHITECTURE.md` for system design
-- **Decisions**: See `docs/core/DECISIONS.md` for ADRs
-- **Glossary**: See `docs/core/GLOSSARY.md` for terminology
-- **Patterns**: See `docs/core/PATTERNS.md` for implementation examples
+- **Instant Setup**: `npx cortex-tms init` - 60 seconds to governance docs
+- **Zero Config**: Works out of the box with sensible defaults
+- **CI Ready**: GitHub Actions templates included
+- **Production Grade**: 316 tests (97% pass rate), enterprise-grade security (v3.2)
+- **Open Source**: MIT license, community-driven
 
----
+**Tested With**: Claude Code, GitHub Copilot (in VS Code). Architecture supports any AI tool.
 
-## 🎯 Why Cortex TMS? Three Pillars, Measurable Results
+---
 
-### 💰 Cost Efficiency (Pillar 1)
+## Community & Support
 
-**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)
+### Get Help
 
-**How**: HOT/WARM/COLD tiers ensure AI only reads what matters (3,647 vs 66,834 tokens)
+- **[GitHub Discussions](https://github.com/cortex-tms/cortex-tms/discussions)** - Ask questions, share ideas
+  - [Q&A](https://github.com/cortex-tms/cortex-tms/discussions/categories/q-a) - Get help from community
+  - [Ideas](https://github.com/cortex-tms/cortex-tms/discussions/categories/ideas) - Suggest features
+  - [Show and Tell](https://github.com/cortex-tms/cortex-tms/discussions/categories/show-and-tell) - Share projects
 
-### ✅ Quality (Pillar 2)
+### Report Issues
 
-**Before TMS**: **40% pattern violations** from AI reading outdated examples
-**After TMS**: **80% fewer violations** with Guardian semantic validation
-**Impact**: Guardian enforces `PATTERNS.md` and `DOMAIN-LOGIC.md` automatically
+- **[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
 
-**How**: LLM-powered review catches semantic drift that grep/regex can't find (**zero false negatives**)
+### Contributing
 
-### 🌱 Sustainability (Pillar 3)
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute
+- **[Community Guide](docs/COMMUNITY.md)** - Community guidelines
 
-**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
+**Star us on GitHub** ⭐ if Cortex TMS helps your AI development workflow!
 
-**How**: Stop reading COLD files unless explicitly needed
+---
 
-### 🚀 Developer Experience
+## Roadmap
 
-- **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
+**v4.0** (Current - Feb 2026):
+- ✅ Staleness detection (git-based, v1)
+- ✅ Archive command
+- ✅ Validation-first positioning
+- ✅ Token claims removed
 
----
+**v4.1** (Planned - Mar 2026):
+- 🔄 Git hooks integration (`cortex-tms hooks install`)
+- 🔄 Staleness v2 (improved heuristics, fewer false positives)
+- 🔄 Incremental doc updates
 
-## Contact
+**v4.2+** (Future):
+- 📋 MCP Server (expose docs to any AI tool)
+- 📋 Multi-tool config generation (.cursorrules, .windsurfrules)
+- 📋 Skills integration
 
-- **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
+See [FUTURE-ENHANCEMENTS.md](FUTURE-ENHANCEMENTS.md) for full roadmap.
 
 ---
 
 ## License
 
-MIT
+MIT - See [LICENSE](LICENSE) for details
 
 ---
 
 ## 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**: 4.0.0 (In Development)
+**Last Updated**: 2026-02-21
+**Current Sprint**: v4.0 - "Quality Governance & Staleness Detection"
 
-<!-- @cortex-tms-version 3.1.0 -->
+<!-- @cortex-tms-version 4.0.0 -->