memorylink 1.0.0

package/CURSOR_AI_V1.4_NEXT_STEPS.md

@@ -0,0 +1,314 @@
+# MemoryLink v1.4 - Instructions for Cursor AI
+
+**Date**: 2025-12-19  
+**Status**: v1.4 Fully Implemented - Ready for Verification & Polish
+
+---
+
+## 1. What MemoryLink v1.4 Now Is
+
+**v1.4 is a production-ready memory + safety layer** with the following complete features:
+
+### Core Features ✅
+
+- **v1.4 Schema** - Enhanced MemoryRecord with:
+  - `sensitivity` (public/internal/secret)
+  - `trustLevel` (high/medium/low)
+  - `status` (DRAFT/VERIFIED)
+  - `provenance` (who, when, how, tool, commit, branch, PR)
+  - `sourceType` (human/code/agent/external)
+  - Full backward compatibility with v1.3
+
+- **Migration System** - `memorylink migrate --to 1.4`:
+  - Safe defaults for v1.3 → v1.4 transformation
+  - Backup creation (`.backup` files)
+  - Dry-run support
+  - Tested with 4008+ entries
+
+- **Buddy-Check CLI** - `memorylink doctor --preflight/--postflight`:
+  - Status: GREEN/YELLOW/RED
+  - Validation checks:
+    - Schema validation
+    - Referential integrity
+    - Security (secrets, PII)
+    - Staleness detection
+    - Policy validation
+    - Consistency checks
+  - JSON output (`--json` flag)
+  - File output (`.memorylink/preflight.json`, `.memorylink/postflight.json`)
+
+- **Override Logging**:
+  - Environment variables: `MEMORYLINK_OVERRIDE_BY`, `MEMORYLINK_OVERRIDE_REASON`
+  - Logged to `.memorylink/overrides.log` (JSONL)
+  - Stored in report structure
+
+- **Observability Log**:
+  - Automatic logging to `.memorylink/observability.log` (JSONL)
+  - Captures: status, duration, trust levels, issues, override info
+  - Statistics function available
+
+- **VS Code Integration**:
+  - Status bar indicator (GREEN/YELLOW/RED)
+  - Sidebar panel (MemoryRecords + Buddy-Check issues)
+  - AI action hooks (preflight/postflight commands)
+  - **Uses CLI as source of truth** (no re-implementation)
+
+- **Mode Configuration**:
+  - Developer mode (default): warnings, no blocking
+  - Enterprise/Strict mode: blocks on RED, requires override
+  - Config: `.memorylink/config.json` with `mode` and `strict` fields
+
+- **CI Integration Example**:
+  - GitHub Actions workflow (`.github/workflows/memorylink-preflight.yml`)
+  - Runs preflight on PR/push
+  - Fails on RED status
+  - Uploads report artifact
+
+**Everything in the agreed v1.4 scope is built and tested.**
+
+---
+
+## 2. What Cursor Should Do Now (Immediate Next Steps)
+
+### A. Keep the CLI as the Single Source of Truth
+
+**Critical**: All safety logic lives in `memorylink doctor`. VS Code / Cursor should **only call the CLI**, not re-implement checks.
+
+**Use these commands**:
+```bash
+# Preflight (before AI operations)
+memorylink doctor --preflight --json [--for <agent>] [--branch <branch>] [--pr <number>]
+
+# Postflight (after AI operations)
+memorylink doctor --postflight --changed --json [--fix]
+```
+
+**Do NOT**:
+- Copy secret/PII detection logic into the extension
+- Re-implement schema validation
+- Duplicate staleness checks
+- Create parallel safety systems
+
+**The extension should**:
+- Call CLI commands
+- Parse JSON responses
+- Display results in UI
+- Handle mode-based behavior
+
+---
+
+### B. Verify IDE Wiring End-to-End
+
+Confirm the following work correctly:
+
+#### 1. Status Bar Indicator
+- [ ] Shows latest Buddy-Check result (GREEN/YELLOW/RED)
+- [ ] Updates when report files change
+- [ ] Click opens report file
+- [ ] Color coding correct (green/yellow/red)
+
+**Test**: Run `memorylink doctor --preflight`, verify status bar updates.
+
+#### 2. Sidebar Panel
+- [ ] Lists recent MemoryRecords with v1.4 fields:
+  - Trust level badges (high/medium/low)
+  - Sensitivity badges (public/internal/secret)
+  - Status badges (DRAFT/VERIFIED)
+- [ ] Shows Buddy-Check issues:
+  - Grouped by file
+  - Severity indicators (error/warning/info)
+  - Suggestions displayed
+- [ ] Auto-refreshes on file changes
+
+**Test**: Open sidebar, verify badges and issues display correctly.
+
+#### 3. Commands
+Verify these commands work:
+- [ ] `MemoryLink: Run Preflight Check`
+  - Calls `memorylink doctor --preflight --json`
+  - Shows result in UI
+  - Updates status bar
+- [ ] `MemoryLink: Run Postflight Check`
+  - Calls `memorylink doctor --postflight --changed --json`
+  - Shows result in UI
+  - Updates status bar
+- [ ] `MemoryLink: Show Buddy-Check Report`
+  - Opens latest report file
+  - Or shows JSON in editor
+
+**Test**: Run each command, verify CLI is called and UI updates.
+
+---
+
+### C. Validate Mode Behavior
+
+#### Developer Mode (`mode: 'developer'`, `strict: false`)
+- [ ] Preflight runs but **does NOT hard-block** AI actions
+- [ ] Shows warnings for YELLOW/RED
+- [ ] Allows AI operations to proceed
+- [ ] Low friction workflow
+
+**Test**: Set mode to developer, run preflight with RED status, verify AI can still proceed.
+
+#### Enterprise/Strict Mode (`mode: 'enterprise'` or `strict: true`)
+- [ ] RED from preflight **blocks** AI actions
+- [ ] RED from postflight **blocks** commits/apply
+- [ ] Override required (with `approvedBy` + `reason`)
+- [ ] Override logged to `.memorylink/overrides.log`
+
+**Test**: Set mode to enterprise, run preflight with RED, verify blocking and override flow.
+
+---
+
+### D. Smoke-Test CI Example
+
+Test the provided `.github/workflows/memorylink-preflight.yml`:
+
+1. **Copy workflow to a test repo**
+2. **Trigger workflow** (push or PR)
+3. **Verify behavior**:
+   - On GREEN/YELLOW → job passes ✅
+   - On RED → job fails ❌
+   - Report artifact uploaded
+   - Summary shown in GitHub Actions UI
+
+**Expected Results**:
+- Workflow runs successfully
+- Preflight check executes
+- Status correctly parsed from JSON
+- Job fails on RED (exit code 1)
+- Artifact contains report
+
+---
+
+## 3. What NOT to Change Now
+
+**Explicitly do NOT add or redesign these yet:**
+
+### ❌ No New Safety Logic in Extension
+- Do not copy secret/PII detection into extension
+- Do not re-implement schema validation
+- Do not duplicate staleness checks
+- Keep all logic in CLI
+
+### ❌ No Future Features Yet
+- Real-time checkpoints
+- Agent locking
+- Smart filtering
+- Project scoping
+- Encryption
+- Dashboard
+- These belong to **v1.5/v2.0**
+
+### ❌ No Schema Changes
+- Do not modify canonical JSONL format
+- Do not change MemoryRecord structure
+- v1.4 schema is final for this version
+
+**Focus**: Verify existing integration works, polish UX, fix bugs.
+
+---
+
+## 4. How Cursor Can Help Next
+
+Once basic verification passes:
+
+### A. Dogfood v1.4
+- Use v1.4 in real Cursor workflows
+- Normal dev work with AI agents
+- Run preflight/postflight during actual coding
+- Identify friction points
+
+### B. File Issues
+- If UX feels heavy in developer mode → file issue
+- If strict mode needs better prompts → file issue
+- If status bar/sidebar has bugs → file issue
+- If CLI integration has problems → file issue
+
+### C. Prepare v1.5 Design
+- Start design notes for v1.5 features:
+  - Checkpoints
+  - Agent locking
+  - Smart filtering
+  - Project scoping
+- **Important**: v1.5 features should also call CLI, not re-implement logic
+- Build on stable v1.4 base
+
+---
+
+## 5. Quick Reference
+
+### CLI Commands
+```bash
+# Preflight
+memorylink doctor --preflight --json
+
+# Postflight
+memorylink doctor --postflight --changed --json
+
+# Migration
+memorylink migrate --to 1.4 --dry-run
+```
+
+### Config Structure
+```json
+{
+  "version": "1.4.0",
+  "mode": "developer",
+  "strict": false
+}
+```
+
+### Report Files
+- `.memorylink/preflight.json` - Latest preflight report
+- `.memorylink/postflight.json` - Latest postflight report
+- `.memorylink/overrides.log` - Override history (JSONL)
+- `.memorylink/observability.log` - Check telemetry (JSONL)
+
+### VS Code Commands
+- `memorylink.showBuddyCheck` - Show report
+- `memorylink.runPreflight` - Run preflight
+- `memorylink.runPostflight` - Run postflight
+
+---
+
+## 6. Validation Checklist
+
+Before moving to v1.5, verify:
+
+- [ ] Status bar shows correct status (GREEN/YELLOW/RED)
+- [ ] Sidebar displays MemoryRecords with badges
+- [ ] Sidebar shows Buddy-Check issues grouped by file
+- [ ] Preflight command works and updates UI
+- [ ] Postflight command works and updates UI
+- [ ] Developer mode doesn't block AI actions
+- [ ] Enterprise mode blocks on RED
+- [ ] Override flow works in strict mode
+- [ ] CI workflow runs and fails on RED
+- [ ] All CLI commands functional
+- [ ] No duplicate safety logic in extension
+
+---
+
+## Summary
+
+**v1.4 is complete.** All features are built, tested, and integrated.
+
+**Cursor's role now**:
+1. Verify the integration works end-to-end
+2. Test mode behavior (developer vs enterprise)
+3. Smoke-test CI example
+4. File issues for UX improvements
+5. Prepare v1.5 design (on top of stable v1.4 base)
+
+**Do not** add new features or redesign existing ones. Focus on verification and polish.
+
+**Once verified**, we move to v1.5 planning with a stable foundation.
+
+---
+
+**Reference Documents**:
+- `V1.4_COMPLETE_VALIDATION_DOCUMENT.md` - Full implementation details
+- `V1.4_INTEGRATION_TEST_RESULTS.md` - Test results
+- `V1.4_INTEGRATION_COMPLETE.md` - Integration summary
+

package/CURSOR_BREAK_IT_TEST.md

@@ -0,0 +1,389 @@
+# Cursor Prompt – Final End-to-End "Break MemoryLink" Test
+
+You are testing a tool called **MemoryLink** on a real JS/TS Git repo.
+
+MemoryLink provides:
+
+- Git-native memory (`.memorylink/` JSONL)  
+- Buddy-Check (`memorylink doctor --preflight/--postflight`)  
+- Locks (`memorylink lock ...`)  
+- Checkpoints (`memorylink checkpoint ...`)  
+- Scopes (`memorylink scopes ...`)  
+- Stats (`memorylink stats ...`)  
+- Optional telemetry (disabled by default)
+
+**Goal**: **Act like a hostile but honest tester**. Try to break things or find gaps. After each scenario, run the right MemoryLink commands and see if they detect problems. If something dangerous happens with no signal, that is a gap.
+
+---
+
+## 0. Setup Assumptions
+
+Assume:
+
+- Repo is a JS/TS project with backend + frontend + shared utils.  
+- MemoryLink is installed and configured (`.memorylink/config.json` exists).  
+- Protected paths include: `auth/`, `migrations/`, `billing/`, `config/production.yml`.  
+- Telemetry is **disabled** (`telemetry.enabled` is false).
+
+If anything is missing, add minimal config/files clearly.
+
+**Setup Commands**:
+```bash
+# Verify MemoryLink is initialized
+memorylink status
+
+# Verify protected files
+cat .memorylink/protected.txt
+
+# Verify config
+cat .memorylink/config.json
+```
+
+---
+
+## Scenario 1 – Big Destructive Refactor
+
+**Task**:
+
+1. Plan and perform a **large refactor** that:
+   - Deletes at least one shared util file used in multiple places.  
+   - Renames or moves a core backend file.  
+
+2. **Steps**:
+
+   - Create a checkpoint before changes:  
+     ```bash
+     memorylink checkpoint create --name "pre-refactor"
+     ```
+   - Run preflight check:  
+     ```bash
+     memorylink doctor --preflight
+     ```
+   - Make the changes (deletes + moves).  
+   - Run postflight check:  
+     ```bash
+     memorylink doctor --postflight
+     ```
+   - Check checkpoint diff:  
+     ```bash
+     memorylink checkpoint diff --name "pre-refactor"
+     ```
+   - Check stats:  
+     ```bash
+     memorylink stats
+     ```
+
+**Check**:
+
+- Does Buddy-Check warn about large change / missing files / drift?  
+- Can checkpoint diff clearly show what changed?
+- Does stats show any warnings or issues?
+
+**If something obviously dangerous happens and MemoryLink says nothing, note it.**
+
+---
+
+## Scenario 2 – Secrets and PII in Code
+
+**Task**:
+
+1. Add a new file `src/backend/payment-logging.ts` that:
+
+   - Logs a fake card number, CVV, and email to a file.  
+   - Logs full request body.  
+   - Example:
+     ```typescript
+     // src/backend/payment-logging.ts
+     import * as fs from 'fs';
+     
+     export function logPayment(data: any) {
+       const cardNumber = '4532-1234-5678-9010';
+       const cvv = '123';
+       const email = 'user@example.com';
+       
+       const logData = {
+         cardNumber,
+         cvv,
+         email,
+         fullRequest: data
+       };
+       
+       fs.writeFileSync('payment.log', JSON.stringify(logData));
+     }
+     ```
+
+2. **Steps**:
+
+   - Implement the file.  
+   - Run postflight check:  
+     ```bash
+     memorylink doctor --postflight
+     ```
+   - Check stats:  
+     ```bash
+     memorylink stats
+     ```
+   - Check if file was created:  
+     ```bash
+     ls -la payment.log
+     ```
+
+**Check**:
+
+- Does Buddy-Check flag any secrets/PII or risky logging?  
+- Does stats show any security warnings?
+- If not, note that this is still a "framework gap" for v1.6 patterns.
+
+---
+
+## Scenario 3 – Protected Auth Bypass
+
+**Task**:
+
+1. Edit a protected file, e.g. `auth/middleware.ts`, to:
+
+   - Add a bypass for a debug header (`x-debug-admin`).  
+   - Log "TEMPORARY BYPASS" in code.  
+   - Example:
+     ```typescript
+     // auth/middleware.ts
+     export function authMiddleware(req: any, res: any, next: any) {
+       // TEMPORARY BYPASS for debugging
+       if (req.headers['x-debug-admin'] === 'true') {
+         console.log('TEMPORARY BYPASS - DEBUG MODE');
+         return next();
+       }
+       // ... normal auth logic
+     }
+     ```
+
+2. **Steps**:
+
+   - Confirm `auth/` is in `.memorylink/protected.txt`:  
+     ```bash
+     cat .memorylink/protected.txt | grep auth
+     ```
+   - Run preflight check:  
+     ```bash
+     memorylink doctor --preflight
+     ```
+   - Make the bypass change.  
+   - Run postflight check:  
+     ```bash
+     memorylink doctor --postflight
+     ```
+   - Check stats:  
+     ```bash
+     memorylink stats
+     ```
+
+**Check**:
+
+- Does Buddy-Check say anything about protected file edits or suspicious changes?  
+- Does stats show any policy violations?
+- If not, note this as a case where v1.6 Git-diff logic must improve.
+
+---
+
+## Scenario 4 – Multi-Agent Lock Conflict
+
+**Simulate two agents**:
+
+1. **Agent A**:
+
+   - Run:  
+     ```bash
+     memorylink lock acquire --agent "AgentA" --files "src/backend/feature-x.ts"
+     ```
+   - Make some changes in `src/backend/feature-x.ts`.  
+   - Check lock status:  
+     ```bash
+     memorylink lock status
+     ```
+
+2. **Agent B** (simulated in another terminal/session):
+
+   - Try to acquire lock:  
+     ```bash
+     memorylink lock acquire --agent "AgentB" --files "src/backend/feature-x.ts"
+     ```
+   - Check lock status:  
+     ```bash
+     memorylink lock status
+     ```
+
+3. **Release and verify**:
+
+   - Agent A releases:  
+     ```bash
+     memorylink lock release
+     ```
+   - Agent B tries again:  
+     ```bash
+     memorylink lock acquire --agent "AgentB" --files "src/backend/feature-x.ts"
+     ```
+   - Verify:  
+     ```bash
+     memorylink lock status
+     ```
+
+**Check**:
+
+- Is Agent B blocked or told that a lock is already held?  
+- Does status clearly show the lock holder and expiry?
+- Can Agent B acquire lock after Agent A releases?
+
+---
+
+## Scenario 5 – Stale Memory vs Code
+
+**Task**:
+
+1. Add a memory entry (via your normal MemoryLink path) that says:  
+   - "We always use Redis for sessions in this project."
+
+   ```bash
+   memorylink memory "We always use Redis for sessions in this project" --tags sessions,redis
+   ```
+
+2. In reality, implement sessions using a database instead of Redis.
+
+   - Create `src/backend/sessions.ts`:
+     ```typescript
+     // src/backend/sessions.ts
+     import { db } from './database';
+     
+     export async function getSession(sessionId: string) {
+       // Using database, NOT Redis
+       return await db.query('SELECT * FROM sessions WHERE id = ?', [sessionId]);
+     }
+     ```
+
+3. **Steps**:
+
+   - Verify memory entry exists:  
+     ```bash
+     memorylink memories | grep -i redis
+     ```
+   - Get context for session work:  
+     ```bash
+     memorylink get-context --smart --task "work on sessions"
+     ```
+   - Run postflight check:  
+     ```bash
+     memorylink doctor --postflight
+     ```
+   - Check stats:  
+     ```bash
+     memorylink stats
+     ```
+
+**Check**:
+
+- Does context show the stale/wrong memory?  
+- Does Buddy-Check or stats give any hint of inconsistency?
+- Is this purely a v1.6 code-analysis gap?
+
+---
+
+## After Running All Scenarios
+
+For each scenario, answer:
+
+1. **Did MemoryLink run without crashing?**  
+   - Yes / No
+   - If No, what error occurred?
+
+2. **Did Buddy-Check / stats give any useful warnings?**  
+   - Yes / No
+   - What warnings were shown?
+
+3. **Was any truly dangerous change completely silent?**  
+   - Yes / No
+   - If Yes, describe the dangerous change
+
+4. **What worked well?**  
+   - List features that detected issues correctly
+
+5. **What gaps were found?**  
+   - List any gaps or limitations discovered
+
+---
+
+## Documenting Gaps
+
+For any silent, clearly dangerous case, create a short note in the repo in a `GAPS_FOR_V1_6.md` file with:
+
+**Format**:
+```markdown
+## Scenario X: [Scenario Name]
+
+**What happened**: [Description of the dangerous change]
+
+**What we expected MemoryLink to do**: [Expected detection/warning]
+
+**What MemoryLink actually did**: [Actual behavior]
+
+**Gap Type**:
+- [ ] Detection gap (needs new rule)
+- [ ] Design/UX gap (user didn't understand output)
+- [ ] Framework gap (v1.6 enhancement needed)
+
+**Priority**: High / Medium / Low
+
+**Notes**: [Additional context]
+```
+
+**Do NOT change MemoryLink code in this test**; the goal is to surface gaps, not to fix them now.
+
+---
+
+## Summary Template
+
+After running all scenarios, create a summary:
+
+```markdown
+# MemoryLink "Break It" Test Results
+
+**Date**: [Date]
+**Tester**: Cursor AI
+**Repo**: [Repo name/path]
+
+## Overall Results
+
+- **Scenarios Run**: 5/5
+- **Crashes**: [Number]
+- **Gaps Found**: [Number]
+- **Features Working**: [List]
+
+## Scenario Results
+
+### Scenario 1: Big Destructive Refactor
+- Status: [Pass/Fail/Gap]
+- Notes: [Details]
+
+### Scenario 2: Secrets and PII
+- Status: [Pass/Fail/Gap]
+- Notes: [Details]
+
+### Scenario 3: Protected Auth Bypass
+- Status: [Pass/Fail/Gap]
+- Notes: [Details]
+
+### Scenario 4: Multi-Agent Lock Conflict
+- Status: [Pass/Fail/Gap]
+- Notes: [Details]
+
+### Scenario 5: Stale Memory vs Code
+- Status: [Pass/Fail/Gap]
+- Notes: [Details]
+
+## Recommendations
+
+- [List any recommendations for v1.6]
+```
+
+---
+
+**Run these scenarios end-to-end and summarize where MemoryLink behaves well and where it needs new rules or UX in v1.6.**
+