feat: manifest-driven installer, lite mode, tests, and CI

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run installer smoke tests
+        run: python tests/test_installer.py
+      - name: Verify installer dry-run
+        run: python scripts/install_cortex.py --dry-run
+      - name: Verify --list-files
+        run: python scripts/install_cortex.py --list-files

MANIFEST.yaml

@@ -23,6 +23,10 @@ documentation:
   agent_policy: docs/agent-policy.md
   templates: docs/templates.md
   using_with_agents: docs/using-with-agents.md
+lite_files:
+  - PROJECT_CONTEXT.md
+  - CURRENT_STATUS.md
+  - AGENT_HANDOFF.md
 required_project_files:
   - PROJECT_CONTEXT.md
   - CURRENT_STATUS.md

README.md

@@ -143,18 +143,17 @@ On first application, the agent should:
 
 ### 5. Review the installed outputs
 
-After first use, the target repository should contain:
+After first use, the target repository should contain `.cortex/` with the installed template files.
+
+**Full mode** (default) installs all 11 governance files.
+**Lite mode** (`--lite`) installs only the 3 essential files for smaller projects:
 - `.cortex/PROJECT_CONTEXT.md`
 - `.cortex/CURRENT_STATUS.md`
 - `.cortex/AGENT_HANDOFF.md`
-- `.cortex/QUICK_REFERENCE.md`
-- `.cortex/PLANOS_ABC.md`
-- `.cortex/LEARNING_LEDGER.md`
-- `.cortex/REGRESSION_MAP.md`
-- `.cortex/IMPROVEMENT_BACKLOG.md`
-- `.cortex/AUDIT_MATRIX.md`
-- `.cortex/RESTRUCTURING_PLAN.md`
-- `.cortex/OPERATOR_PROFILE.md`
+
+You can upgrade from Lite to Full at any time by running the installer again without `--lite`.
+
+For an example of filled `.cortex/` files, see [`examples/filled-cortex/`](examples/filled-cortex/).
 
 ## Using CORTEX with coding agents
 
@@ -217,7 +216,9 @@ Apply the attached CORTEX package to this target project autonomously. Read STAR
 - `adapters/` — agent-specific operating notes
 - `templates/` — standard files installed into `.cortex/`
 - `scripts/` — installation tooling
-- `examples/` — first-use example prompt
+- `examples/` — first-use prompt and filled `.cortex/` example
+- `tests/` — installer smoke tests
+- `.github/workflows/` — CI pipeline
 
 ## License
 

docs/installing.md

@@ -23,14 +23,30 @@ List the managed files without writing anything:
 python3 scripts/install_cortex.py --list-files
 ```
 
-## Install the template set
+## Install the full template set
 
 ```bash
 python3 scripts/install_cortex.py /path/to/target-repo
 ```
 
 By default, existing `.cortex/` files are preserved.
 
+## Install in Lite mode
+
+Lite mode installs only the 3 essential files (PROJECT_CONTEXT, CURRENT_STATUS, AGENT_HANDOFF) — ideal for small projects or first-time adoption:
+
+```bash
+python3 scripts/install_cortex.py /path/to/target-repo --lite
+```
+
+To upgrade from Lite to Full later, run the installer again without `--lite`:
+
+```bash
+python3 scripts/install_cortex.py /path/to/target-repo
+```
+
+Existing files are preserved; only the missing ones are added.
+
 ## Overwrite existing template files
 
 Use `--force` only when you intentionally want the repository's current `.cortex/` template files replaced by the versions from this package:
@@ -41,7 +57,11 @@ python3 scripts/install_cortex.py /path/to/target-repo --force
 
 ## What gets installed
 
-The installer creates `.cortex/` in the target repository and manages the standard template set defined in [`MANIFEST.yaml`](../MANIFEST.yaml).
+The installer reads [`MANIFEST.yaml`](../MANIFEST.yaml) to determine which files to install:
+- **Full mode** (default): all files listed in `required_project_files`
+- **Lite mode** (`--lite`): only the files listed in `lite_files`
+
+To see a worked example of filled `.cortex/` files, see [`examples/filled-cortex/`](../examples/filled-cortex/).
 
 After installation, the next step is not feature work by default.
 The operator or agent should return to [`START.md`](../START.md), inspect repository reality, and populate the installed files with evidence from the target project.

docs/templates.md

@@ -16,5 +16,24 @@ Each file has a distinct role:
 - `RESTRUCTURING_PLAN.md` sequences structural evolution.
 - `OPERATOR_PROFILE.md` captures operator preferences and safety boundaries.
 
+## Lite vs Full
+
+**Lite mode** (3 files) is recommended for small projects or first-time adoption:
+- `PROJECT_CONTEXT.md` — what the project is
+- `CURRENT_STATUS.md` — where it stands now
+- `AGENT_HANDOFF.md` — how to continue safely
+
+**Full mode** (11 files) adds governance, audit, and knowledge management for larger or more complex projects.
+
+To install in Lite mode: `python3 scripts/install_cortex.py <target> --lite`
+
+Upgrading from Lite to Full is seamless — run the installer again without `--lite` and only the missing files are added.
+
+## Example
+
+See [`examples/filled-cortex/`](../examples/filled-cortex/) for a realistic example of filled `.cortex/` files based on a fictional project.
+
+## Design principles
+
 The templates are intentionally lightweight.
 They should be populated with repository evidence, not generic filler.

examples/filled-cortex/AGENT_HANDOFF.md

@@ -0,0 +1,48 @@
+# AGENT_HANDOFF
+
+## Read first
+1. .cortex/PROJECT_CONTEXT.md
+2. .cortex/CURRENT_STATUS.md
+3. this file
+
+## Session goal
+- Current objective: Fix inventory sync race condition (PATCH /api/inventory/:id)
+- Do not touch: Stripe integration, auth flow, database schema
+- Primary risks: Race condition can cause inventory count to go negative; email failures are silent
+
+## Branch procedure
+```bash
+git remote -v
+git branch --show-current
+git status --short
+# LAST_STABLE_BRANCH = main
+git switch main
+git pull origin main
+git switch -c agent/[agent-name]-inventory-fix
+```
+
+If the working tree is dirty and you did not create those changes, stop and document the state before branching.
+
+## What happened last session
+- Installed .cortex/ and completed first audit
+- Identified root cause of race condition: no row-level lock on inventory updates
+- Documented 2 confirmed issues and 1 suspected issue
+- Created initial REGRESSION_MAP and LEARNING_LEDGER entries
+- Did NOT make code changes (Advisory Mode)
+
+## What remains
+- Implement row-level locking fix in src/api/inventory.js
+- Add error handling to src/services/email.js
+- Profile WebSocket handler for suspected memory leak
+- Set up basic test coverage (currently 0%)
+
+## Before finishing
+- Update `.cortex/CURRENT_STATUS.md`
+- Update this file with what changed and what remains
+- Record new risks or repeated regressions in the relevant CORTEX files
+
+## Never do this
+- never start on main
+- never merge to main
+- never force push
+- never run destructive commands without operator confirmation

examples/filled-cortex/CURRENT_STATUS.md

@@ -0,0 +1,38 @@
+# CURRENT_STATUS
+
+## Current phase
+- Name: Post-MVP stabilization
+- Confidence: Medium — core features work but infrastructure is fragile
+
+## Last stable branch
+- Name: main
+- Evidence: Last merged PR #34 passed manual QA on 2025-12-10; no regressions reported since
+
+## Last update
+- Date: 2025-12-15
+- Agent: Claude Code (Opus)
+- Branch: agent/claude-stabilization-pass
+- Completed: First CORTEX audit, inventory sync race condition documented, regression map started
+
+## Current task
+- Objective: Fix inventory sync race condition before adding new features
+- Mode: Advisory (investigating root cause)
+
+## Next safe step
+- Action: Add database-level locking to inventory update endpoint (src/api/inventory.js:45-78)
+- Why this is safe: Isolated to one endpoint, existing tests cover the happy path, rollback is trivial
+
+## Known issues
+- Confirmed: Race condition in PATCH /api/inventory/:id under concurrent edits
+- Confirmed: SendGrid email fails silently (no error handling in src/services/email.js)
+- Suspected: Memory leak in WebSocket handler (needs profiling)
+
+## CSEI snapshot
+- Structure: 3
+- Clarity: 3
+- Safety: 2
+- Verification: 1
+- Continuity: 4
+- Recoverability: 3
+- Regression Pressure: 2
+- Final CSEI: 51

examples/filled-cortex/PROJECT_CONTEXT.md

@@ -0,0 +1,26 @@
+# PROJECT_CONTEXT
+
+## Identity
+- Project name: MeuApp
+- Project goal: SaaS platform for small business inventory management
+- Current phase: Post-MVP stabilization
+- Primary users: Small business owners (non-technical)
+
+## Technical snapshot
+- Frontend: React 18 + Tailwind CSS
+- Backend: Node.js + Express
+- Database: PostgreSQL 15
+- Auth: Supabase Auth (email + Google OAuth)
+- Integrations: Stripe (payments), SendGrid (email)
+- Deploy: Vercel (frontend) + Railway (backend + DB)
+
+## Reality check
+- What exists today: Working MVP with product CRUD, basic inventory tracking, user auth, Stripe checkout
+- What is unstable: Inventory sync has race conditions under concurrent edits; email notifications fail silently
+- What is missing: Reporting dashboard, export to CSV, multi-user per business
+- What should not be touched yet: Stripe integration (working, certified, no reason to change)
+
+## Evidence
+- Key files reviewed: src/api/inventory.js, src/api/auth.js, src/components/Dashboard.tsx, package.json
+- Key branches reviewed: main (stable), feat/reports (abandoned, conflicts), fix/inventory-sync (in progress)
+- Key unknowns: No test coverage metrics; deploy pipeline has no staging environment

examples/filled-cortex/README.md

@@ -0,0 +1,23 @@
+# Example: Filled .cortex/
+
+This folder shows how a `.cortex/` directory looks **after** a real CORTEX session.
+
+The example is based on a fictional SaaS project (MeuApp — inventory management for small businesses) that was built with AI and needs stabilization.
+
+## Files included
+
+These are the 3 essential files (Lite mode):
+
+- **PROJECT_CONTEXT.md** — what the project is, its tech stack, and what's stable vs. fragile
+- **CURRENT_STATUS.md** — where the project stands right now, CSEI score, next safe step
+- **AGENT_HANDOFF.md** — everything the next agent needs to continue safely
+
+## How to use this example
+
+Compare these filled files with the blank templates in `templates/` to understand what kind of information each file should contain.
+
+Key principles:
+- Fill with **observable evidence**, not assumptions
+- Be specific: file paths, line numbers, branch names, dates
+- Mark unknowns explicitly rather than guessing
+- The goal is that any capable agent can read these files and resume work without asking questions