v1.1.0: Issue lifecycle ledger + living REPORT.md documentation

Adds persistent audit trail: every issue is tracked across scans with
deterministic fingerprints. Issues auto-transition open → fixed → regressed.

New tools: get_history, log_fix, acknowledge_issue, get_report.
Each full_stack_audit now generates .codemax/REPORT.md with health
dashboard, trend graphs, fix log, and API contract map.

88 passing tests across 5 suites.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+
+      - name: Type check
+        run: npm run lint

.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [1.1.0] - 2026-03-29
+
+### Added
+- **Issue lifecycle ledger** — persistent tracking of every issue across scans with deterministic fingerprinting. Issues transition through `open → fixed → regressed` automatically.
+- **Living REPORT.md** — auto-generated Markdown report at `.codemax/REPORT.md` with health dashboard, trend graphs, open issues with evidence, fix log, regression history, and API contract map. Readable by any developer without running CodeMax.
+- **Health trend tracking** — audit snapshots stored over time, showing health score progression across up to 50 scans.
+- **Regression detection** — previously fixed issues that reappear are automatically flagged as regressions with full history.
+- **Fix logging** — `log_fix` tool to document *how* an issue was resolved, recorded in the ledger and REPORT.md.
+- **Issue acknowledgment** — `acknowledge_issue` tool to mark intentional/acceptable issues so they don't clutter action items.
+
+### New Tools (4)
+- `get_history` — audit trail with health trend, issue lifecycle, and scan statistics
+- `log_fix` — manually document how an issue was resolved
+- `acknowledge_issue` — mark issues as intentional/acceptable
+- `get_report` — read the generated `.codemax/REPORT.md`
+
+### Changed
+- `full_stack_audit` now automatically persists results to `.codemax/ledger.json` and generates `.codemax/REPORT.md`
+- Audit summary now includes a "Changes Since Last Scan" section showing new issues, fixes, and regressions
+- Auto-adds `.codemax/` to project `.gitignore`
+
+---
+
 ## [1.0.0] - 2026-03-28
 
 ### Added

README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org)
-[![Tools](https://img.shields.io/badge/MCP_Tools-9-purple)]()
+[![Tools](https://img.shields.io/badge/MCP_Tools-13-purple)]()
 
 ---
 
@@ -122,6 +122,15 @@ CodeMax detects cross-stack issues that frontend-only or backend-only tools stru
 | `map_dependencies` | Map all connections between frontend files and backend routes. Find orphans and phantoms. |
 | `check_env` | Cross-reference .env files against actual usage in frontend and backend code. |
 
+### Documentation & History
+
+| Tool | Description |
+|------|-------------|
+| `get_history` | Audit trail — health trend over time, issue lifecycle (new, fixed, regressed), scan statistics. Filter by status. |
+| `log_fix` | Document how a specific issue was resolved. Recorded in the ledger and appears in REPORT.md. |
+| `acknowledge_issue` | Mark an issue as intentional/acceptable. Won't be flagged as action items in future reports. |
+| `get_report` | Read the living REPORT.md — all issues, fixes, trends, and contract maps in one document. |
+
 ### Individual Scans
 
 | Tool | Description |
@@ -194,6 +203,61 @@ Overall: B (78/100)
 
 ---
 
+## Project Documentation (`.codemax/`)
+
+Every audit automatically persists results to a `.codemax/` directory in your project. This gives your team a living audit trail without needing to run CodeMax themselves.
+
+```
+.codemax/
+├── ledger.json     # Issue lifecycle tracking (all issues, ever)
+└── REPORT.md       # Human-readable living document
+```
+
+### REPORT.md
+
+A Markdown file any developer can read — no tools needed. Updated on every `full_stack_audit`:
+
+- **Health Dashboard** — current scores across all 6 dimensions
+- **Health Trend** — score over time, so you can see if things are improving
+- **Latest Scan Changes** — what's new, what's fixed, what regressed
+- **Open Issues** — every issue with evidence, code snippets, and fix suggestions
+- **Fix Log** — table of everything that was resolved, when, and how
+- **Regression History** — issues that were fixed but came back
+- **API Contract Map** — full frontend-to-backend connection table
+- **Project Structure** — detected frameworks, ORM, paths
+
+### Issue Lifecycle
+
+Issues are tracked through their lifecycle across scans:
+
+```
+Discovered ──► open ──► fixed (disappears from next scan)
+                │                    │
+                ▼                    ▼
+          acknowledged          regressed (comes back)
+         (intentional)               │
+                                     ▼
+                                   fixed (again)
+```
+
+- **Auto-detection**: Issues are automatically marked `fixed` when they disappear from a scan
+- **Manual logging**: Use `log_fix` to document *how* something was resolved
+- **Regression tracking**: If a fixed issue reappears, it's flagged as `regressed`
+- **Deterministic fingerprints**: Same issue = same fingerprint, even if line numbers shift
+
+### Example Workflow
+
+```
+1. Run `full_stack_audit` → finds 8 issues, creates .codemax/REPORT.md
+2. Fix 3 issues in your code
+3. Run `full_stack_audit` again → auto-detects 3 fixes, finds 1 new issue
+4. Use `log_fix CTR-X-a1b2c3 "Added Zod validation to POST /api/users"` → records the how
+5. Use `acknowledge_issue DEP-B-d4e5f6` → dead endpoint is intentional (consumed by mobile app)
+6. Open .codemax/REPORT.md → full audit trail, readable by anyone
+```
+
+---
+
 ## Example Output
 
 ### `full_stack_audit`
@@ -324,25 +388,29 @@ npm test
 ```
 src/
 ├── index.ts                    # Entry point (stdio transport)
-├── server.ts                   # MCP server + 9 tool registrations
+├── server.ts                   # MCP server + 13 tool registrations
 ├── types.ts                    # Shared type definitions
 ├── analyzers/
 │   ├── project-detector.ts     # Framework, monorepo, ORM detection
 │   ├── frontend-scanner.ts     # API call extraction (fetch, axios, SWR, etc.)
 │   ├── backend-scanner.ts      # Route extraction (Next.js, Express, etc.)
 │   └── env-analyzer.ts         # Environment variable cross-referencing
 ├── bridge/
-│   ├── orchestrator.ts         # Full audit coordination
+│   ├── orchestrator.ts         # Full audit coordination + ledger integration
 │   ├── contract-analyzer.ts    # Frontend ↔ backend contract comparison
 │   ├── correlator.ts           # Cross-stack issue detection
 │   └── health-scorer.ts        # 6-dimension health scoring
+├── tools/
+│   ├── ledger-manager.ts       # Issue lifecycle tracking (fingerprint, fix, regress)
+│   └── report-writer.ts        # Living REPORT.md generation
 ├── utils/
 │   └── helpers.ts              # URL normalization, scoring, formatting
 └── __tests__/
     ├── helpers.test.ts          # Unit tests for utilities
     ├── project-detector.test.ts # Project detection tests
     ├── contract-analyzer.test.ts# Contract analysis tests
-    └── scanners.test.ts         # Frontend + backend scanner tests
+    ├── scanners.test.ts         # Frontend + backend scanner tests
+    └── ledger.test.ts           # Ledger lifecycle tests
 ```
 
 ---
@@ -371,6 +439,11 @@ Contributions welcome. [Open an issue](https://github.com/rish-e/codemax/issues)
 - [x] Server Actions support
 - [x] Environment variable cross-referencing
 - [x] Health scoring (6 dimensions)
+- [x] Issue lifecycle ledger (open → fixed → regressed)
+- [x] Living REPORT.md documentation
+- [x] Fix logging with descriptions
+- [x] Health trend tracking across audits
+- [x] Regression detection
 - [ ] GraphQL schema ↔ query contract analysis
 - [ ] tRPC router ↔ client contract analysis
 - [ ] Auto-fix engine (generate patches for common issues)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemax",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The full-stack MCP that bridges frontend and backend analysis — sees what single-side tools miss.",
   "type": "module",
   "main": "dist/index.js",