# DX-91 Regression Surfaces Inventory

**Task:** `inventory-regression-surfaces`  
**Commit:** `706a201` (main branch)  
**Date:** 2026-03-12

---

## Overview

This document inventories every behavior surface that DX-91 (Invar Simplification) can break before destructive changes begin. It serves as the anchor for all harness work in this phase.

---

## 1. Init/Dev-Sync Outputs (BEHAVIOR SURFACE)

### 1.1 Files Generated by `invar init` (Current v1)

| File | Current Behavior | DX-91 Change | Risk Level |
|------|-----------------|--------------|------------|
| `CLAUDE.md` | Multi-region markers (`critical`, `managed`, `project`, `user`) | Single `<!--invar:begin-->`/`<!--invar:end-->` | **HIGH** |
| `INVAR.md` | Full protocol (~434 lines) | Simplified agent spec (~70-120 lines) | **HIGH** |
| `.invar/context.md` | Project context, task router | **DELETED** (not generated) | **MEDIUM** |
| `.invar/examples/` | Code examples for agents | **DELETED** (not generated) | **MEDIUM** |
| `.claude/skills/` | 8 skill templates | **DELETED** (not generated) | **HIGH** |
| `.claude/hooks/` | PreToolUse, PostToolUse, Stop | **DELETED** (not generated) | **HIGH** |
| `.claude/commands/` | /audit, /guard commands | **DELETED** (not generated) | **MEDIUM** |
| `.pi/hooks/` | Pi-specific hooks | **DELETED** (not generated) | **MEDIUM** |
| `.pi/tools/` | Pi custom tools | **DELETED** (not generated) | **MEDIUM** |
| `.pre-commit-config.yaml` | Full config with multiple hooks | Single `invar guard` hook | **LOW** |
| `.mcp.json` | Auto-generated | **NOT generated** (manual setup) | **LOW** |

### 1.2 Files Affected by `invar dev sync`

| File | Current | Post-DX-91 | Risk Level |
|------|---------|------------|------------|
| `CLAUDE.md` | Regenerates all regions | Regenerates single region | **HIGH** |
| `INVAR.md` | Full protocol | Simplified spec | **HIGH** |
| `.invar/examples/` | Syncs examples | **REMOVED** | **MEDIUM** |
| `.claude/skills/` | Syncs skills | **REMOVED** | **HIGH** |
| `.claude/hooks/` | Syncs hooks | **REMOVED** | **HIGH** |

---

## 2. Migration Paths (BEHAVIOR SURFACE)

### 2.1 v1 → v2 Migration Triggers

A project is considered **v1** if ANY of these exist:
- `.claude/skills/` directory
- `.claude/hooks/` directory  
- `.pi/hooks/` directory
- `.pi/tools/` directory
- `.invar/examples/` directory
- `INVAR.md` with v1 managed header comment
- `CLAUDE.md` with `<!--invar:critical-->` or `<!--invar:managed-->` markers

### 2.2 Migration Behavior Changes

| Scenario | Current Behavior | Post-DX-91 Behavior | Risk |
|----------|-----------------|-------------------|------|
| Fresh init (no v1) | Interactive prompts | Non-interactive direct creation | **HIGH** |
| v1 detected | Silent merge | **REQUIRES preview + confirmation** | **HIGH** |
| Re-run init | Appends/replaces | Replaces between single markers | **MEDIUM** |
| Backup failure | N/A | **ABORTS migration** (required) | **HIGH** |

### 2.3 Destructive Cleanup

| Action | Current | Post-DX-91 | Risk |
|--------|---------|------------|------|
| Delete skills | N/A | Delete `.claude/skills/` (if present) | **HIGH** |
| Delete hooks | N/A | Delete `.claude/hooks/` (if present) | **HIGH** |
| Delete examples | N/A | Delete `.invar/examples/` (if present) | **MEDIUM** |
| Preserve user data | N/A | Backup `.invar/context.md` → `.invar/backup/v1-context.md` | **MEDIUM** |

---

## 3. Template Merge Seams (BEHAVIOR SURFACE)

### 3.1 Current Region Markers (v1)

```markdown
<!--invar:critical-->
...
<!--/invar:critical-->

<!--invar:managed version="5.0"-->
...
<!--/invar:managed-->

<!--invar:project-->
...
<!--/invar:project-->

<!--invar:user-->
...
<!--/invar:user-->
```

### 3.2 Post-DX-91 Markers (v2)

```markdown
<!--invar:begin-->
...
<!--invar:end-->
```

### 3.3 Merge Logic Changes

| Scenario | Current | Post-DX-91 |
|----------|---------|------------|
| File doesn't exist | Create | Create |
| File exists, no markers | Append | Append |
| File exists, has markers | Replace regions | Replace single region |
| User content outside markers | Preserved | Preserved |

---

## 4. Packaging/Install Touchpoints (BEHAVIOR SURFACE)

### 4.1 CLI Commands Removed

| Command | File | Lines | Impact |
|---------|------|-------|--------|
| `invar update` | `commands/update.py` | ~200 | Users lose auto-update |
| `invar uninstall` | `commands/uninstall.py` | ~200 | Users lose clean uninstall |
| `invar test` | `commands/test.py` | ~200 | Redundant (use guard) |
| `invar verify` | N/A (merged into guard) | ~200 | Redundant (use guard) |
| `invar mutate` | `commands/mutate.py` | ~150 | Niche, removed |
| `invar rules` | N/A | ~150 | Low usage |
| `invar version` | N/A | ~50 | Use `--version` flag |
| `invar feedback *` | `commands/feedback.py` | ~300 | DX-79 removed |
| `invar hooks *` | `commands/hooks.py` | ~200 | Skills removed |
| `invar skill *` | `commands/skill.py` | ~300 | Skills removed |

### 4.2 Commands Kept

| Command | File | Status |
|---------|------|--------|
| `invar guard` | `commands/guard.py` | ✅ Unchanged |
| `invar sig` | `commands/perception.py` | ✅ Unchanged (Python-only) |
| `invar map` | `commands/perception.py` | ✅ Unchanged (Python-only) |
| `invar refs` | `commands/perception.py` | ✅ Unchanged (Python-only) |
| `invar init` | `commands/init.py` | ⚠️ **Rewritten** |
| `invar doc *` | `commands/doc.py` | ✅ Unchanged |
| `invar dev sync` | `commands/template_sync.py` | ⚠️ **Reduced scope** |

### 4.3 TypeScript Support Removed

| Component | Path | Lines | Impact |
|-----------|------|-------|--------|
| Node tools | `node_tools/` | ~5,981 | **DELETED** |
| TS compiler wrapper | `shell/ts_compiler.py` | ~300 | **DELETED** |
| TS guards | `prove/guard_ts.py` | ~200 | **DELETED** |
| TS parsers | `core/ts_*.py` | ~500 | **DELETED** |
| TS routing in commands | Various | ~500 | **Removed** |

---

## 5. Highest-Risk Repo Paths

### 5.1 Core Regression Fixtures (Python-only Behavior)

These paths define the simplified Python-only behavior that harness tests must validate:

| Path | Purpose | Fixture Type |
|------|---------|--------------|
| `src/invar/core/template_parser.py` | Region marker parsing | **CORE** - must adapt to single-marker |
| `src/invar/core/template_helpers.py` | Template merge logic | **CORE** - must adapt to new markers |
| `src/invar/shell/commands/init.py` | Init command | **CORE** - rewritten for v2 |
| `src/invar/shell/templates.py` | Template rendering | **CORE** - simplified |
| `src/invar/shell/template_engine.py` | Jinja2 engine | **CORE** - fewer templates |
| `src/invar/templates/manifest.toml` | Template config | **CORE** - reduced entries |

### 5.2 End-to-End Harness Entrypoints

These are the integration points that validate the complete workflow:

| Entrypoint | Validates | Surface Type |
|------------|-----------|--------------|
| `invar init` (fresh) | Non-interactive v2 init | **E2E** |
| `invar init --preview --claude` | Preview mode works in non-interactive CLI | **E2E** |
| `invar init` (v1 detected) | Migration preview + confirmation | **E2E** |
| `invar dev sync` | Regenerates CLAUDE.md + INVAR.md | **E2E** |
| `invar guard` | Python-only verification | **E2E** |
| MCP `invar_guard` | Contract verification | **E2E** |

### 5.3 Paths NOT Affected (Safe)

These paths remain unchanged and don't need regression fixtures:

| Path | Reason |
|------|--------|
| `src/invar/core/rules.py` | Core rules unchanged |
| `src/invar/core/contracts.py` | @pre/@post unchanged |
| `runtime/src/invar_runtime/` | Runtime package unchanged |
| `src/invar/shell/doc_tools.py` | Doc tools unchanged |
| `src/invar/mcp/handlers.py` | MCP tools unchanged (Python-only) |

---

## 6. Mapping Table: Surface → Files → Owning Step

| Surface | Files/Entrypoints | Owning Future Step |
|---------|-------------------|-------------------|
| **Init v2 Behavior** | `commands/init.py` | DX-91 Regression Fixtures |
| **Migration Preview** | `commands/init.py` (migration path) | DX-91 Regression Fixtures |
| **Marker Parsing** | `core/template_parser.py` | DX-91 Regression Fixtures |
| **Template Rendering** | `shell/templates.py`, `template_engine.py` | DX-91 Regression Fixtures |
| **CLI Commands** | `commands/*.py` (11 removed) | DX-91 CLI Rewrite |
| **TypeScript Removal** | `node_tools/`, `ts_compiler.py` | DX-91 TypeScript Strip |
| **Generated Files** | `CLAUDE.md`, `INVAR.md` generation | DX-91 Template Rewrite |
| **E2E Integration** | Full init/dev-sync/guard flow | DX-91 E2E Harness |

---

## 7. Fixtures Required

### 7.1 Core Regression Fixtures

These fixtures capture pre-DX-91 behavior for regression testing:

| Fixture | Purpose | Location |
|---------|---------|----------|
| `fixture_v1_claude_md` | v1 CLAUDE.md with multi-region markers | `tests/fixtures/dx91/` |
| `fixture_v1_invar_md` | Full v1 INVAR.md | `tests/fixtures/dx91/` |
| `fixture_v1_full_project` | Full v1 project layout | `tests/fixtures/dx91/` |
| `fixture_v2_claude_md` | v2 CLAUDE.md (target) | `tests/fixtures/dx91/` |
| `fixture_v2_invar_md` | Simplified INVAR.md (target) | `tests/fixtures/dx91/` |
| `fixture_migration_preview` | Expected migration preview output | `tests/fixtures/dx91/` |

### 7.2 End-to-End Harness Entrypoints

| Test | Validates | Entry Point |
|------|-----------|--------------|
| `test_init_fresh_v2` | Non-interactive v2 init on fresh project | CLI: `invar init` |
| `test_init_migration_preview` | v1 detection + preview output | CLI: `invar init` |
| `test_init_migration_confirm` | Confirmation prompt + execution | CLI: `invar init` |
| `test_dev_sync_v2` | CLAUDE.md + INVAR.md regeneration | CLI: `invar dev sync` |
| `test_guard_python_only` | Guard runs without TS code | CLI: `invar guard` |
| `test_mcp_guard_python_only` | MCP guard without TS code | MCP: `invar_guard` |

---

## 8. Scope Boundary for Later Steps

### 8.1 In Scope for This Inventory

- [x] Init/dev-sync outputs enumerated
- [x] Migration paths identified
- [x] Template merge seams documented
- [x] Packaging/install touchpoints mapped
- [x] Core regression fixtures identified
- [x] E2E harness entrypoints identified

### 8.2 Out of Scope (Later Steps)

- Fixture implementation (step: regression-fixtures)
- Runtime rewrites (step: runtime-preservation)
- CLI command rewrites (step: cli-rewrite)
- Template rewrites (step: template-rewrite)

### 8.3 Conflict Control

**This inventory anchors all harness work.** Later harness steps MUST:
1. Use fixtures defined here (don't create duplicates)
2. NOT modify core regression fixture locations
3. Coordinate with this inventory before creating new fixtures

---

## 9. Discovered Issues

### Issue 1: Marker Parsing Compatibility

**Location:** `src/invar/core/template_parser.py:76-77`

**Problem:** Current parser uses four region patterns (`critical`, `managed`, `project`, `user`). DX-91 introduces single marker (`begin`/`end`). Parser needs update.

**Impact:** HIGH - Affects CLAUDE.md merge logic

**Recommendation:** Add new pattern support while maintaining backward compatibility for v1 detection

---

### Issue 2: Migration Detection Logic

**Location:** `src/invar/shell/commands/init.py` (detection scattered)

**Problem:** v1 detection criteria are spread across the codebase. Need centralized detection for migration preview.

**Impact:** HIGH - Affects migration preview

**Recommendation:** Create single `detect_v1_layout()` function with clear criteria

---

### Issue 3: CLI Flag Changes

**Location:** `src/invar/shell/commands/init.py:356-386`

**Problem:** Current init has `--claude`, `--pi`, `--mcp-only`, `--language` flags. DX-91 removes these.

**Impact:** MEDIUM - Breaking change for existing scripts

**Recommendation:** Document migration path for users with scripted init

---

## 10. Verification Commands

```bash
# Verify init generates expected v2 output
invar init --preview --claude

# Verify migration detection works
# (Test with v1 project layout)

# Verify guard works without TS
invar guard

# Verify dev sync scope reduced (dry-run equivalent)
invar dev sync --check
```

---

**END OF INVENTORY**
