mindforge-cc 11.2.1 → 11.3.1

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]    |                      |

package/.mindforge/org/integrations/INTEGRATIONS-CONFIG.md

@@ -0,0 +1,58 @@
+# MindForge Integrations Configuration
+# IMPORTANT: Never store API tokens, passwords, or private keys in this file.
+# Credentials belong in environment variables or a managed secrets service.
+
+## Jira Configuration
+JIRA_BASE_URL=https://your-org.atlassian.net
+JIRA_PROJECT_KEY=ENG
+JIRA_EPIC_LABEL=mindforge-phase
+JIRA_STORY_TYPE=Story
+JIRA_BUG_TYPE=Bug
+JIRA_STORY_POINTS_FIELD=story_points
+
+## Confluence Configuration
+CONFLUENCE_BASE_URL=https://your-org.atlassian.net/wiki
+CONFLUENCE_SPACE_KEY=ENG
+CONFLUENCE_ARCHITECTURE_PAGE_TITLE=MindForge Architecture
+CONFLUENCE_ADR_PARENT_PAGE_TITLE=Architecture Decision Records
+CONFLUENCE_PHASE_DOCS_PARENT_PAGE_TITLE=Sprint Documentation
+CONFLUENCE_AUTO_PUBLISH=false
+
+## Slack Configuration
+SLACK_CHANNEL_ID=C01234ABCDE
+SLACK_NOTIFY_ON=phase_complete,security_finding,approval_needed,blocker
+SLACK_MENTION_ON_CRITICAL=@oncall
+SLACK_USE_THREADS=true
+
+## Governance Configuration
+TIER2_APPROVERS=senior-engineer-1,senior-engineer-2,tech-lead
+TIER3_APPROVERS=security-officer,compliance-officer,cto
+EMERGENCY_APPROVERS=cto,vp-engineering
+TIER2_SLA_HOURS=24
+TIER3_SLA_HOURS=4
+TIER2_ESCALATE_AFTER_HOURS=48
+TIER3_ESCALATE_AFTER_HOURS=8
+TIER2_EXPIRY_HOURS=48
+TIER3_EXPIRY_HOURS=8
+ESCALATION_CONTACT=engineering-lead@your-org.com
+ESCALATION_SLACK_CHANNEL=C0ESCALATE
+
+## GitHub Configuration
+GITHUB_REPO=your-org/your-repo
+GITHUB_DEFAULT_BRANCH=main
+GITHUB_REQUIRED_REVIEWERS=2
+GITHUB_DEFAULT_REVIEWERS=senior-engineer-1,senior-engineer-2
+GITHUB_PR_TEMPLATE_PATH=.github/pull_request_template.md
+GITHUB_DRAFT_BY_DEFAULT=false
+
+## GitLab Configuration
+GITLAB_PROJECT_ID=
+GITLAB_DEFAULT_BRANCH=main
+GITLAB_DEFAULT_REVIEWERS=
+
+## Notification Preferences
+NOTIFY_PHASE_COMPLETE=true
+NOTIFY_SECURITY_CRITICAL=true
+NOTIFY_APPROVAL_NEEDED=true
+NOTIFY_MILESTONE_COMPLETE=true
+NOTIFY_BLOCKER_ADDED=true