mindforge-cc 11.3.0 → 11.3.1

package/.mindforge/memory/MEMORY-SCHEMA.md

@@ -0,0 +1,155 @@
+# MindForge v2 — Knowledge Graph Schema
+
+## Overview
+
+The MindForge knowledge graph is built from five JSONL files — all append-only,
+all at `.mindforge/memory/`. Every entry has a consistent base schema plus
+type-specific fields.
+
+## Base schema (all entry types)
+
+```json
+{
+  "id":               "kb-uuid-v4",
+  "timestamp":        "ISO-8601",
+  "type":             "architectural_decision|code_pattern|bug_pattern|team_preference|domain_knowledge",
+  "topic":            "Short title (≤ 80 chars)",
+  "content":          "Full knowledge content (no limit)",
+  "source":           "Where this was captured: 'Phase 3 retro', 'Debug session 2026-01', 'Manual entry'",
+  "project":          "project-name from PROJECT.md",
+  "confidence":       0.0,
+  "tags":             ["tag1", "tag2"],
+  "linked_adrs":      ["ADR-007"],
+  "times_referenced": 0,
+  "last_referenced":  null,
+  "deprecated":       false,
+  "deprecated_by":    null
+}
+```
+
+## Type-specific schemas
+
+### `architectural_decision`
+
+Extended fields:
+
+```json
+{
+  "decision":     "Use argon2id for password hashing",
+  "rationale":    "bcrypt is showing its age; argon2id is the modern standard",
+  "alternatives": ["bcrypt", "scrypt", "pbkdf2"],
+  "phase_number": 3,
+  "adr_reference": "ADR-007"
+}
+```
+
+Capture trigger: Phase completion (ADR files extracted), `/mindforge:discuss-phase`
+
+### `code_pattern`
+
+Extended fields:
+
+```json
+{
+  "pattern_type": "good|anti-pattern",
+  "language":     "typescript",
+  "example_good": "// Code showing the correct pattern",
+  "example_bad":  "// Code showing the incorrect pattern (for anti-patterns)",
+  "applies_to":   ["auth", "database", "api"]
+}
+```
+
+Capture trigger: Smart compaction Block D, debug session root cause
+
+### `bug_pattern`
+
+Extended fields:
+
+```json
+{
+  "bug_category":   "auth|database|api|ui|performance|security",
+  "symptom":        "Login works in tests but fails in production with cookie errors",
+  "root_cause":     "httpOnly cookies require HTTPS; dev server was HTTP",
+  "fix":            "Enable HTTPS in dev or use secure: false in development only",
+  "prevention":     "Always configure cookie settings per-environment",
+  "severity_when_missed": "HIGH",
+  "recurrence_count": 1
+}
+```
+
+Capture trigger: Debug session completion, security findings, retrospective "what went wrong"
+
+### `team_preference`
+
+Extended fields:
+
+```json
+{
+  "preference_type": "style|tool|process|convention|architecture",
+  "applies_when":    "When implementing auth",
+  "preference":      "Always use argon2id, never bcrypt. See ADR-007.",
+  "strength":        "strong|moderate|weak",
+  "override_allowed": true
+}
+```
+
+Capture trigger: Retrospective "what should we keep doing", steering instructions,
+MINDFORGE.md changes from retrospective
+
+### `domain_knowledge`
+
+Extended fields:
+
+```json
+{
+  "domain":     "JWT security",
+  "tech_stack": ["node.js", "typescript"],
+  "knowledge":  "JWT access tokens should be short-lived (15 min). Refresh tokens in httpOnly cookies, not localStorage. Never decode JWT without verifying signature.",
+  "source_url": "https://auth0.com/docs/secure/tokens/json-web-tokens",
+  "verified_at": "2026-01-15"
+}
+```
+
+Capture trigger: Research engine output, `/mindforge:remember --add`
+
+## Confidence scoring
+
+Confidence (0.0–1.0) represents how strongly this knowledge should be applied:
+
+| Confidence | Meaning | How set |
+| :--- | :--- | :--- |
+| 0.9–1.0 | Strong team decision — always apply | Manual entry, strong steering, ADR |
+| 0.7–0.9 | Clear pattern — apply unless there's a reason not to | Retrospective, debug session |
+| 0.5–0.7 | Observed pattern — consider but verify | Smart compaction Block D |
+| 0.3–0.5 | Weak signal — informational only | Single observation |
+| < 0.3 | Hypothesis — don't apply proactively | Auto-captured, unverified |
+
+## Confidence reinforcement
+
+Each time an entry is referenced (retrieved and the advice was followed):
+
+```bash
+confidence = min(1.0, confidence + 0.05)
+times_referenced += 1
+```
+
+Each time an entry is contradicted (a different decision was made):
+
+```bash
+confidence = max(0.0, confidence - 0.10)
+```
+
+## Deprecation
+
+When a knowledge entry becomes outdated (e.g., team switches from argon2id to Passkeys):
+
+```json
+{
+  "deprecated": true,
+  "deprecated_by": "kb-uuid-of-newer-entry",
+  "deprecated_reason": "Superseded by WebAuthn/Passkeys approach (ADR-031)"
+}
+```
+
+Deprecated entries are never deleted — they are excluded from active retrieval
+but available for historical queries.

package/.mindforge/memory/engine/capture-protocol.md

@@ -0,0 +1,36 @@
+# MindForge v2 — Knowledge Capture Protocol
+
+## Purpose
+
+The Capture Engine automatically extracts valuable engineering knowledge from session artifacts to ensure that project-specific wisdom is preserved beyond a single handoff.
+
+## Capture Triggers
+
+MindForge monitors the following lifecycle events for knowledge extraction:
+
+1. **Phase Completion**: Extracting architectural decisions from `PROJECT.md` and phase retrospectives.
+2. **Hardened Debugging**: Capturing "root cause -> fix" patterns from completed debug reports.
+3. **Manual Command**: Using `/mindforge:remember --add` to explicitly record team preferences or domain knowledge.
+4. **ADR Generation**: Parsing newly created Architecture Decision Records.
+
+## Extraction Logic
+
+The extraction process (via `knowledge-capture.js`) involves:
+
+- **Structural Parsing**: Identifying standardized headings (e.g., "Decision", "Root Cause", "Pattern").
+- **Deduplication**: Checking for existing entries with similar content to prevent knowledge bloat.
+- **Initial Confidence**: Assigning a default confidence score (usually 0.5) to newly captured entries.
+- **Auto-Tagging**: Inferring tags based on the file path and content context (e.g., `#nodejs`, `#security`).
+
+## Inhibitors (What NOT to capture)
+
+To prevent the knowledge base from becoming "noisy", the system ignores:
+
+- Transient session state (e.g., local file counts).
+- Intermediate debugging steps that didn't lead to a fix.
+- Content marked with `#no-capture` or inside blocks labeled "Confidential".
+
+## Retention Policy
+
+- **Append-only**: Entries are never physically deleted.
+- **Deprecation**: Outdated entries are marked as `deprecated: true` and replaced by newer entries with the same `source_id`.

package/.mindforge/memory/engine/global-sync-spec.md

@@ -0,0 +1,42 @@
+# MindForge v2 — Global Knowledge Sync Specification
+
+## Purpose
+
+Allow knowledge to flow between projects via a machine-level global store.
+Team members can promote project-specific insights to their global knowledge base,
+which loads into every future project's session start.
+
+## Storage locations
+
+- **Project-local:** `.mindforge/memory/knowledge-base.jsonl` (per repo)
+- **Global (machine):** `~/.mindforge/global-knowledge-base.jsonl` (per developer)
+
+## Sync rules
+
+- Promotion is MANUAL — nothing is auto-promoted to global. Use `/mindforge:remember --promote [ID]`.
+- Loading is AUTOMATIC — global entries load at every session start if relevant.
+- Project entries take precedence over global entries (same ID = local wins).
+- Global entries receive a metadata flag `global: true` but are ranked alongside project entries based on relevance.
+
+## What should be promoted to global
+
+Good candidates for global promotion:
+
+- Language-agnostic security practices ("always validate input before database queries")
+- Technology-specific best practices learned through experience ("argon2id over bcrypt")
+- Universal debugging patterns ("check the timezone mismatch before blaming async code")
+- Cross-project architectural preferences ("Repository pattern over active record")
+
+## Global entry metadata
+
+When promoted to global, entries gain:
+
+```json
+{
+  "global": true,
+  "promoted_at": "ISO-8601",
+  "promoted_from_project": "saas-app",
+  "promoted_by": "git-config-user-email",
+  "global_applicability": "all|typescript|nodejs|react|[specific]"
+}
+```

package/.mindforge/memory/engine/retrieval-spec.md

@@ -0,0 +1,44 @@
+# MindForge v2 — Knowledge Retrieval Specification
+
+## Purpose
+
+The Retrieval Engine is responsible for identifying and loading the most relevant pieces of long-term memory into the current session context to improve agent performance and consistency.
+
+## Components
+
+- **Indexer (`knowledge-indexer.js`)**: Handles the scoring and ranking of knowledge entries.
+- **Session Loader (`session-memory-loader.js`)**: Orchestrates the loading of relevant memories at the start of a session.
+
+## Scoring Logic (TF-IDF + Heuristics)
+
+Relevance is calculated using a multi-factor scoring model:
+
+1. **Text Search (TF-IDF)**:
+    - Tokenizes the query and knowledge text.
+    - Calculates Term Frequency (TF) and Inverse Document Frequency (IDF).
+    - Entries must have a positive TF-IDF score to be considered relevant if keywords are present.
+
+2. **Confidence & Recency**:
+    - **Confidence Score**: Boosts entries with higher confidence levels (reinforced over time).
+    - **Recency Decay**: Prefer more recent knowledge entries, especially for bug patterns.
+
+3. **Tag Overlap**:
+    - Queries can include required tags (e.g., `#typescript`).
+    - Entries with matching tags receive a significant boost.
+
+4. **Inhibitors**:
+    - Deprecated entries are never retrieved.
+    - Low-confidence "noise" entries are filtered out.
+
+## Context Injection
+
+During session start, the loader:
+1. Performs a broad search based on the current project's primary technology stack and recent activities.
+2. Selects the top `N` (default 5-10) most relevant entries.
+3. Injects them into the agent's secondary context (e.g., as a dedicated "Memory context" block).
+
+## SDK Interface
+
+```typescript
+const relevantKnowledge = await memory.query("query string", ["#tag1"], 5);
+```

package/.mindforge/memory/sync-manifest.json

@@ -0,0 +1,6 @@
+{
+  "pattern-library.jsonl": {
+    "lastSync": "2026-06-04T19:08:39.438Z",
+    "localCount": 1
+  }
+}

package/.mindforge/metrics/METRICS-SCHEMA.md

@@ -0,0 +1,42 @@
+# MindForge Metrics — Schema Reference
+
+## Files
+- `session-quality.jsonl`
+- `phase-metrics.jsonl`
+- `skill-usage.jsonl`
+- `compaction-quality.jsonl`
+
+All files are append-only JSONL.
+
+## session-quality.jsonl fields
+- session_id, date, phase, developer_id
+- tasks_attempted, tasks_completed, tasks_failed
+- verify_pass_rate, quality_gates_failed
+- security_findings, context_compactions
+- skills_loaded_count, antipatterns_detected
+- session_quality_score, session_quality_score_raw
+
+Score formula:
+- base 100
+- minus task/gate/security/antipattern penalties
+- bonus for zero gate failures and zero security findings
+- keep both raw and clamped (`0-100`) score for trend analysis
+
+## phase-metrics.jsonl fields
+- phase lifecycle and delivery coverage
+- difficulty score
+- security and UAT outcomes
+- phase_quality_score
+
+## skill-usage.jsonl fields
+- date, phase, plan
+- skill_name, skill_version
+- trigger_type (`text_match|file_path_match|file_name_match`)
+- trigger_keyword
+- task_outcome, verify_passed_first_try
+
+## compaction-quality.jsonl fields
+- date, compaction_level, context_pct_at_compaction
+- decisions_captured, discoveries_captured
+- implicit_knowledge_items, quality_signals_captured
+- next_session_continuation_success (auto-inferred where possible)

package/.mindforge/metrics/quality-tracker.md

@@ -0,0 +1,32 @@
+# MindForge Metrics — Quality Tracker
+
+## Trend windows
+- short: last 5 sessions
+- medium: last 20 sessions
+- long: all sessions
+
+## Key targets
+- Verify pass rate > 85% (warning < 75%)
+- Task failure rate < 10% (warning > 20%)
+- Compactions < 1 per 8 tasks (warning > 2 per session)
+
+## Early warnings
+- quality score drop >= 10 points over 3 sessions
+- any CRITICAL security finding after clean streak
+- compaction overhead > 2/session
+- stale skills not triggered in 10 sessions
+
+## Quality metrics -> agent behaviour adjustment
+Automatic adjustments at session start:
+
+- If verify pass rate < 75% over last 3 sessions:
+  tighten verify-step determinism checks before execution.
+- If last-session task failure rate > 20%:
+  halve estimated scope and suggest splitting.
+- If compaction frequency > 2/session:
+  proactively summarize every 4 tasks.
+- If security findings trend worsens over 3 phases:
+  force-load `security-review` for all tasks in current phase.
+
+Always report adjustment to user:
+`Quality signal detected: [signal]. Adjusting behaviour: [adjustment].`

package/.mindforge/models/model-registry.md

@@ -0,0 +1,48 @@
+# MindForge v2 — Model Registry
+# Version: v2.0.0-alpha.3
+
+MindForge v2 uses a tiered multi-model architecture. Models are selected based on the task persona and difficulty tier.
+
+## 1. Primary Reasoning Tier (Tier 1)
+Used for complex architecture, planning, and high-stakes reasoning.
+
+- **Anthropic Claude 3.5 Opus** (`claude-3-opus-20240229`)
+  - Strengths: Deepest reasoning, highly reliable for planning.
+  - Persona mapping: `architect`, `planner`.
+  - Setting: `PLANNER_MODEL`.
+
+- **OpenAI GPT-4o** (`gpt-4o`)
+  - Strengths: Fast reasoning, excellent tool use, adversarial insight.
+  - Persona mapping: `reviewer`, `security-reviewer`.
+  - Setting: `REVIEWER_MODEL`.
+
+## 2. Execution Tier (Tier 2)
+Used for the bulk of code implementation and transformation tasks.
+
+- **Anthropic Claude 3.5 Sonnet** (`claude-3-5-sonnet-20240620`)
+  - Strengths: Balanced speed/quality, best-in-class coding.
+  - Persona mapping: `developer`, `qa-engineer`.
+  - Setting: `EXECUTOR_MODEL`.
+
+- **Google Gemini 1.5 Pro** (`gemini-1.5-pro`)
+  - Strengths: 1M context window, deep codebase research.
+  - Persona mapping: `research-agent`.
+  - Setting: `RESEARCH_MODEL`.
+
+## 3. High-Security/Privacy Tier (Tier 3)
+Used for tasks involving authentication, PII, or financial operations.
+
+- **Anthropic Claude 3.5 Opus** (`claude-3-opus-20240229`)
+  - Setting: `SECURITY_MODEL`.
+
+## 4. Utility/Quick Tier (Tier 4)
+Used for low-ambiguity tasks and micro-transformations.
+
+- **Anthropic Claude 3.5 Haiku** (`claude-3-5-haiku-20241022`)
+  - Setting: `QUICK_MODEL`.
+
+## 5. Fallback Chain
+If a primary model is unavailable (API key missing or 429), follow these defaults:
+1. `gpt-4o` → `claude-3-5-sonnet`
+2. `claude-3-opus` → `gpt-4o`
+3. `gemini-1.5-pro` → `claude-3-5-sonnet` (limited context)

package/.mindforge/models/model-router.md

@@ -0,0 +1,30 @@
+# MindForge v2 — Model Router
+# Version: v2.0.0-alpha.3
+
+## Routing Logic
+
+The MindForge router resolves which model to use at task dispatch time using this algorithm:
+
+1. **Check Persona:** Map the task `<persona>` to a setting key.
+   - `developer` → `EXECUTOR_MODEL`
+   - `architect` → `PLANNER_MODEL`
+   - `security-reviewer` → `SECURITY_MODEL`
+   - `qa-engineer` → `QA_MODEL`
+   - `research-agent` → `RESEARCH_MODEL`
+   - `debug-specialist` → `DEBUG_MODEL`
+   - `unknown` → `EXECUTOR_MODEL`
+
+2. **Check Tier Override:**
+   - If `tier == 3` (Security/Privacy), force `SECURITY_MODEL` regardless of persona.
+
+3. **Check Budget Bias:**
+   - If `difficulty < 2.0` and `MODEL_PREFER_CHEAP_BELOW_DIFFICULTY` is set:
+     - Use `QUICK_MODEL` instead of the resolved model.
+
+4. **Resolve Model ID:**
+   - Read the setting key from `MINDFORGE.md`.
+   - Use baked-in defaults if not present.
+
+5. **Verify Availability:**
+   - Check if matching `[PROVIDER]_API_KEY` is present in environment.
+   - If missing: Apply fallback chain from `model-registry.md`.

package/.mindforge/org/CONVENTIONS.md

@@ -0,0 +1,62 @@
+# Coding Conventions — [ORG NAME]
+
+<!-- These conventions are loaded by every MindForge agent session -->
+<!-- Agents follow these exactly — be precise -->
+
+## Naming conventions
+| Element          | Convention      | Example                        |
+|------------------|-----------------|--------------------------------|
+| Variables        | camelCase        | `userProfile`                  |
+| Functions        | camelCase        | `getUserById`                  |
+| Classes          | PascalCase       | `UserService`                  |
+| Constants        | SCREAMING_SNAKE  | `MAX_LOGIN_ATTEMPTS`           |
+| File names       | kebab-case       | `user-service.ts`              |
+| DB tables        | snake_case plural| `user_profiles`                |
+| DB columns       | snake_case       | `created_at`                   |
+| API endpoints    | kebab-case       | `/user-profiles/{id}`          |
+| Env variables    | SCREAMING_SNAKE  | `DATABASE_URL`                 |
+
+## File structure
+```
+src/
+  features/          ← Feature-based organisation
+    auth/
+      auth.controller.ts
+      auth.service.ts
+      auth.repository.ts
+      auth.types.ts
+      auth.test.ts
+  shared/            ← Shared utilities and types
+  config/            ← Configuration and env validation
+```
+
+## Import order (enforced by linter)
+1. Node.js built-ins
+2. External packages
+3. Internal absolute imports
+4. Internal relative imports
+(Blank line between each group)
+
+## Commit message format (Conventional Commits)
+```
+type(scope): short description
+
+[optional body]
+
+[optional footer: BREAKING CHANGE or closes #issue]
+```
+Types: feat, fix, chore, docs, test, refactor, perf, security, build, ci
+
+## Forbidden patterns
+<!-- Agents will refuse to write code that contains these -->
+- No `var` — use `const` or `let`
+- No `any` type in TypeScript without a comment explaining why
+- No `as unknown as X` type casting without a comment
+- No default exports (use named exports)
+- No `console.log` in production code
+- No empty catch blocks
+- No direct database access from route handlers (use service layer)
+- No business logic in controllers/handlers (use service layer)
+- No hardcoded URLs — use config/environment variables
+- No synchronous file I/O in request handlers
+```

package/.mindforge/org/ORG.md

@@ -0,0 +1,51 @@
+# Organisation Context — [ORG NAME]
+
+<!-- Replace every [placeholder] with your organisation's actual values -->
+<!-- This file is loaded at the start of every MindForge session -->
+
+## Identity
+**Organisation:** [Your organisation name]
+**Mission:** [1-2 sentences: what you build and for whom]
+**Engineering team size:** [number]
+
+## Default tech stack
+| Layer          | Technology          | Version   | Notes                    |
+|----------------|---------------------|-----------|--------------------------|
+| Frontend       | [e.g. Next.js]      | [e.g. 14] | [why this choice]        |
+| Backend        | [e.g. FastAPI]      | [e.g. 0.111] |                       |
+| Database       | [e.g. PostgreSQL]   | [e.g. 16] |                          |
+| Cache          | [e.g. Redis]        | [e.g. 7]  |                          |
+| Infrastructure | [e.g. AWS]          | —         |                          |
+| CI/CD          | [e.g. GitHub Actions] | —       |                          |
+| Monitoring     | [e.g. Datadog]      | —         |                          |
+
+## Architecture defaults
+- API style: [REST / GraphQL / gRPC]
+- Auth: [e.g. JWT with refresh tokens via Supabase Auth]
+- ORM/DB access: [e.g. Prisma with PostgreSQL]
+- Testing framework: [e.g. Vitest + Testing Library]
+- Package manager: [npm / pnpm / yarn / uv]
+
+## Team conventions
+- Git branching: [e.g. Gitflow / trunk-based]
+- PR policy: [e.g. 2 approvals required, CI must pass before merge]
+- Code review: [e.g. Conventional Comments format]
+- Sprint length: [e.g. 2 weeks]
+- Definition of ready: [criteria for a story to enter a sprint]
+- Definition of done: [criteria for a story to be marked complete]
+
+## Enterprise tools
+- Issue tracker: [e.g. Jira — your-org.atlassian.net]
+- Wiki: [e.g. Confluence — your-org.atlassian.net/wiki]
+- Source control: [e.g. GitHub — github.com/your-org]
+- Messaging: [e.g. Slack — your-org.slack.com]
+- Secrets: [e.g. AWS Secrets Manager / HashiCorp Vault]
+
+## Compliance requirements
+<!-- Check all that apply -->
+- [ ] GDPR
+- [ ] HIPAA
+- [ ] SOC 2 Type II
+- [ ] PCI-DSS
+- [ ] ISO 27001
+- [ ] Other: [specify]

package/.mindforge/org/SECURITY.md

@@ -0,0 +1,50 @@
+# Security Policies — [ORG NAME]
+
+<!-- Loaded by MindForge Security Reviewer persona for every security-related task -->
+
+## Authentication standards
+- Passwords: bcrypt with cost factor ≥ 12, or argon2id
+- Tokens: cryptographically random, ≥ 32 bytes (use crypto.randomBytes)
+- JWT access tokens: 15-minute expiry maximum
+- JWT refresh tokens: 7-day expiry, stored in httpOnly, Secure, SameSite=Strict cookie
+- Session IDs: regenerate on any privilege change (login, role change)
+- MFA: required for all admin and privileged accounts
+
+## Authorisation standards
+- Deny by default — grant minimum required permissions
+- Verify permissions server-side on every request
+- Never trust client-sent role or permission claims
+- Log every authorisation failure: user ID, resource, timestamp, IP
+
+## Data protection
+- Encryption at rest: AES-256 for all PII and sensitive data
+- Encryption in transit: TLS 1.2 minimum, TLS 1.3 preferred
+- PII must never appear in application logs
+- Database backups encrypted at rest
+- Data retention policy: [specify your org's policy]
+
+## Secrets management
+- Zero secrets in source code — all via environment variables
+- All production secrets in [your secrets manager]
+- Rotate secrets immediately if exposure is suspected
+- Separate secrets per environment (dev/staging/prod never share)
+
+## Dependency policy
+- Audit new dependencies before adding: CVE check, licence check, maintenance status
+- `npm audit --audit-level=high` must pass in CI before merge
+- No packages with > 6 months without a commit (unless frozen intentionally)
+- Approved licences: MIT, Apache-2.0, BSD-2/3-Clause, ISC
+- Forbidden licences: GPL (without explicit legal approval), AGPL, SSPL
+
+## Incident response
+- P0 (active breach): notify [security contact] immediately, rotate all credentials
+- P1 (critical vulnerability): patch within 24 hours
+- P2 (high vulnerability): patch within 7 days
+- All incidents: postmortem required within 5 business days
+
+## Code review security checklist
+Before approving any PR touching auth, payments, or PII:
+- [ ] OWASP Top 10 reviewed (see security-reviewer.md persona)
+- [ ] No secrets in diff
+- [ ] Input validation on all user-controlled data
+- [ ] New dependencies CVE-scanned

package/.mindforge/org/TOOLS.md

@@ -0,0 +1,53 @@
+# Approved Tools & Libraries — [ORG NAME]
+
+<!-- Reference for all agents when making dependency and tooling decisions -->
+
+## Approved libraries (use these — do not use alternatives without approval)
+
+### Authentication & security
+| Purpose              | Library              | Version  | Notes                    |
+|----------------------|----------------------|----------|--------------------------|
+| Password hashing     | bcrypt               | ^5.1     | Cost factor 12 minimum   |
+| JWT                  | jose                 | ^5.0     | NOT jsonwebtoken (CJS issues) |
+| Crypto               | Node.js built-in     | —        | No third-party for basics |
+
+### HTTP & API
+| Purpose              | Library              | Version  | Notes                    |
+|----------------------|----------------------|----------|--------------------------|
+| HTTP server          | [e.g. Fastify]       | [^4.0]   |                          |
+| Validation           | [e.g. Zod]           | [^3.0]   |                          |
+| HTTP client          | [e.g. ky]            | [^1.0]   | Not axios                |
+
+### Database
+| Purpose              | Library              | Version  | Notes                    |
+|----------------------|----------------------|----------|--------------------------|
+| ORM                  | [e.g. Prisma]        | [^5.0]   |                          |
+| Migrations           | [included in ORM]    | —        |                          |
+
+### Testing
+| Purpose              | Library              | Version  | Notes                    |
+|----------------------|----------------------|----------|
+| Test runner          | [e.g. Vitest]        | [^1.0]   |                          |
+| Mocking              | [e.g. vitest mock]   | —        | Built-in preferred       |
+| E2E                  | [e.g. Playwright]    | [^1.40]  |                          |
+
+## Forbidden libraries (never use these)
+| Library              | Reason                              | Use instead            |
+|----------------------|-------------------------------------|------------------------|
+| jsonwebtoken         | CommonJS, maintenance concerns      | jose                   |
+| moment               | Large bundle, deprecated            | date-fns or Temporal   |
+| lodash               | Unnecessary in modern JS/TS         | Native array methods   |
+| request              | Deprecated                          | ky or fetch            |
+| node-uuid            | Deprecated                          | crypto.randomUUID()    |
+
+## MCP servers (for MindForge integrations)
+| Service              | URL                                 | Purpose                |
+|----------------------|-------------------------------------|------------------------|
+| [e.g. Jira]          | [mcp url]                           | Issue tracking         |
+| [e.g. Confluence]    | [mcp url]                           | Wiki                   |
+
+## CI/CD tool versions
+| Tool                 | Version  | Config file          |
+|----------------------|----------|----------------------|
+| Node.js              | 20 LTS   | .nvmrc               |
+| [package manager]    | [ver]    |                      |