mindforge-cc 1.0.0

package/.mindforge/pr-review/ai-reviewer.md

@@ -0,0 +1,266 @@
+# MindForge — AI PR Review Engine
+
+## Purpose
+Use the Claude API directly to perform intelligent, contextual code reviews
+on pull request diffs. Goes beyond static analysis to provide reasoning-based
+feedback that understands architectural context.
+
+## Review philosophy
+The AI reviewer has three goals:
+1. Catch what static analysis misses (logic errors, design flaws, missing edge cases)
+2. Confirm that the PR delivers what it claims (requirements traceability)
+3. Maintain code quality standards consistently across all reviewers
+
+The AI reviewer does NOT replace human reviewers — it prepares them.
+It surfaces issues, explains context, and asks questions.
+Human reviewers make final decisions.
+
+## Claude API integration
+
+```javascript
+// pr-review/ai-review-runner.js
+
+const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
+if (!ANTHROPIC_API_KEY) {
+  console.error('ANTHROPIC_API_KEY not set — AI review unavailable');
+  process.exit(0); // Graceful skip, not failure
+}
+
+async function runAIReview(diff, context) {
+  const response = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': ANTHROPIC_API_KEY,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: 'claude-sonnet-4-6',
+      max_tokens: 4096,
+      system: buildSystemPrompt(context),
+      messages: [
+        { role: 'user', content: buildReviewPrompt(diff, context) }
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    const err = await response.text();
+    throw new Error(`Claude API error ${response.status}: ${err}`);
+  }
+
+  const data = await response.json();
+  return data.content[0].text;
+}
+```
+
+## System prompt construction
+
+```javascript
+function buildSystemPrompt(context) {
+  return `You are a senior code reviewer performing a pull request review for the project: ${context.projectName}.
+
+## Your review context
+Tech stack: ${context.techStack}
+Architecture pattern: ${context.architecturePattern}
+Coding conventions: ${context.conventions}
+Security requirements: ${context.securityRequirements}
+
+## Your review approach
+1. Read the diff carefully — understand the INTENT of each change, not just the change itself
+2. Check if the implementation matches the stated PR purpose
+3. Look for: logic errors, missing error handling, security issues, performance concerns
+4. Evaluate: code clarity, convention adherence, test coverage
+5. Flag: anything that seems to contradict the architecture or conventions
+
+## Output format
+Produce a structured review in this exact format:
+
+### Summary
+[2-3 sentences: what this PR does and overall quality assessment]
+
+### Findings
+For each finding, use exactly:
+**[CRITICAL|HIGH|MEDIUM|LOW]** \`file:line\` — [Issue description]
+> [Specific recommendation]
+
+### Positive observations
+[What was done well — be genuine, not perfunctory]
+
+### Questions for the author
+[Numbered questions about unclear decisions or assumptions]
+
+### Verdict
+[APPROVE | REQUEST_CHANGES | COMMENT] — [one sentence rationale]
+
+Be direct. Be specific. Cite line numbers. Do not be vague.
+Do not flag issues that are stylistic preferences when conventions permit them.
+Do not repeat findings from the automated checks (secret detection, type errors) — focus on logic and design.`;
+}
+```
+
+## Review prompt construction
+
+```javascript
+function buildReviewPrompt(diff, context) {
+  return `Please review this pull request diff.
+
+## PR Information
+Title: ${context.prTitle}
+Author: ${context.prAuthor}
+Branch: ${context.branch} → ${context.base}
+Files changed: ${context.filesChanged}
+
+## Requirements being addressed
+${context.requirements || 'No specific requirements listed'}
+
+## Architectural context
+${context.architectureContext || 'See ARCHITECTURE.md for system design'}
+
+## The diff
+\`\`\`diff
+${diff}
+\`\`\`
+
+Focus your review on correctness, security, and architectural alignment.
+Do not comment on formatting issues handled by the linter.`;
+}
+```
+
+## Context loading
+
+Before calling the API, load review context:
+```javascript
+function extractConventionsSections(raw) {
+  const sections = [];
+  const forbidden = raw.match(/##\s+Forbidden patterns[\s\S]*?(?=\n##\s+|$)/i);
+  const naming = raw.match(/##\s+Naming conventions[\s\S]*?(?=\n##\s+|$)/i);
+  if (forbidden) sections.push(forbidden[0]);
+  if (naming) sections.push(naming[0]);
+  return sections.join('\n\n').slice(0, 2000);
+}
+
+function loadReviewContext() {
+  const projectMd = readFile('.planning/PROJECT.md');
+  const archMd    = readFile('.planning/ARCHITECTURE.md');
+  const convMd    = readFile('.mindforge/org/CONVENTIONS.md');
+  const secMd     = readFile('.mindforge/org/SECURITY.md');
+
+  return {
+    projectName:         extractField(projectMd, 'NAME') || 'Unknown',
+    techStack:           extractTechStack(projectMd),
+    architecturePattern: extractField(archMd, '## Architectural pattern') || 'Unknown',
+    conventions:         extractConventionsSections(convMd) || convMd.slice(0, 2000),
+    securityRequirements: secMd.slice(0, 1500),
+  };
+}
+```
+
+## Rate limiting and cost management
+
+```javascript
+// Review request limits to control API costs
+// maxDailyReviews is configurable via MINDFORGE.md: AI_REVIEW_DAILY_LIMIT
+const REVIEW_LIMITS = {
+  maxDiffSize: 12000,       // Characters — larger diffs get truncated by file
+  maxFilesReviewed: 20,     // Review the 20 most-changed files
+  cacheTtlMinutes: 60,      // Cache reviews for the same commit SHA
+  maxDailyReviews: 50,      // Stop AI reviews after 50 per day (configurable)
+};
+
+const AI_REVIEW_LOG = path.join(projectRoot, '.mindforge', 'metrics', 'ai-review-usage.jsonl');
+
+function logAIReview(prSha) {
+  const entry = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    pr_sha: prSha,
+    date: new Date().toISOString().slice(0, 10),
+    model: 'claude-sonnet-4-6',
+  }) + '\n';
+
+  // Create parent directory if it doesn't exist
+  const dir = path.dirname(AI_REVIEW_LOG);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  fs.appendFileSync(AI_REVIEW_LOG, entry);
+}
+
+// Before calling API: check daily limit
+function checkDailyLimit(maxReviews) {
+  if (!fs.existsSync(AI_REVIEW_LOG)) return true; // No log = no limit hit
+
+  const today = new Date().toISOString().slice(0, 10);
+  let count = 0;
+
+  const lines = fs.readFileSync(AI_REVIEW_LOG, 'utf8').split('\n').filter(Boolean);
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      if (entry.date === today) count++;
+    } catch {
+      continue; // Skip malformed lines — don't let parse errors break the limit check
+    }
+  }
+
+  return count < maxReviews;
+}
+```
+
+## Diff truncation strategy (file-based)
+
+```javascript
+function buildDiffForReview(fullDiff) {
+  const MAX_CHARS = 12000;
+  const MAX_FILES = 20;
+
+  if (fullDiff.length <= MAX_CHARS) return fullDiff;
+
+  // Prefer showing fewer complete files over more truncated ones
+  // Sort files by change size (largest first — most important to review)
+  const fileDiffs = splitDiffByFile(fullDiff);
+  const sortedFiles = fileDiffs.sort((a, b) => b.content.length - a.content.length);
+
+  let result = '';
+  let fileCount = 0;
+  for (const fileDiff of sortedFiles.slice(0, MAX_FILES)) {
+    if (result.length + fileDiff.content.length > MAX_CHARS) break;
+    result += fileDiff.content + '\n';
+    fileCount++;
+  }
+
+  const omitted = sortedFiles.length - fileCount;
+  if (omitted > 0) {
+    result += `\n[${omitted} file(s) omitted from review — diff too large. Run review with --diff on individual files.]\n`;
+  }
+
+  return result;
+}
+
+function splitDiffByFile(diff) {
+  const files = [];
+  const parts = diff.split(/^diff --git/m).filter(Boolean);
+  for (const part of parts) {
+    const header = part.match(/^a\/(.+) b\//);
+    files.push({
+      filename: header ? header[1] : 'unknown',
+      content: 'diff --git' + part,
+    });
+  }
+  return files;
+}
+```
+
+## Output formatting for GitHub
+
+```javascript
+function formatForGitHub(aiReview, summary) {
+  return `## 🤖 MindForge AI Code Review
+
+${aiReview}
+
+---
+*Generated by MindForge AI Review Engine v${VERSION}*
+*Model: claude-sonnet-4-6 | Context: PROJECT.md + ARCHITECTURE.md + CONVENTIONS.md*
+*This review supplements but does not replace human code review.*`;
+}
+```

package/.mindforge/pr-review/finding-formatter.md

@@ -0,0 +1,46 @@
+# MindForge — PR Review Finding Formatter
+
+## Purpose
+Convert AI review output into structured findings for GitHub, JSON, or Markdown.
+
+## Supported outputs
+
+### GitHub Markdown
+```
+## 🤖 MindForge AI Code Review
+
+### Summary
+...
+
+### Findings
+**[HIGH]** `src/api/auth.ts:47` — Missing token expiry validation
+> Add expiry validation before accepting the token.
+```
+
+### JSON
+```json
+{
+  "summary": "...",
+  "findings": [
+    {
+      "severity": "HIGH",
+      "file": "src/api/auth.ts",
+      "line": 47,
+      "description": "Missing token expiry validation",
+      "recommendation": "Add expiry validation before accepting the token"
+    }
+  ],
+  "verdict": "REQUEST_CHANGES"
+}
+```
+
+### GitHub annotations
+```
+::warning file=src/api/auth.ts,line=47::Missing token expiry validation
+```
+
+## Formatting rules
+- Always preserve severity (CRITICAL/HIGH/MEDIUM/LOW)
+- Include file and line number when present
+- Do not auto-invent line numbers
+- Keep recommendations actionable and specific

package/.mindforge/pr-review/review-prompt-templates.md

@@ -0,0 +1,44 @@
+# MindForge — PR Review Prompt Templates
+
+## Specialised review templates by change type
+
+### Security-focused review (for Tier 3 changes)
+Used when: PR includes auth, payment, PII, or security changes.
+Additional system prompt addition:
+```
+SECURITY REVIEW MODE ACTIVE.
+Apply the OWASP Top 10 checklist systematically to this diff.
+Flag every instance of:
+- A01: Access control bypasses
+- A02: Cryptographic weaknesses (weak algorithms, insecure storage)
+- A03: Injection vectors (SQL, NoSQL, OS, LDAP)
+- A07: Authentication failures (session management, credential handling)
+Any CRITICAL security finding must be listed first, before other findings.
+```
+
+### Database migration review
+Used when: PR includes database schema changes.
+Additional prompt addition:
+```
+DATABASE MIGRATION REVIEW MODE.
+For this migration, verify:
+1. Migration is reversible — is there a DOWN migration?
+2. Migration is non-blocking — does it avoid full table locks?
+3. New columns with NOT NULL have either a DEFAULT or a two-phase migration
+4. No data-loss operations without explicit confirmation in PR description
+5. New indexes are added CONCURRENTLY (PostgreSQL) to avoid table locks
+6. Foreign key constraints are added with VALIDATE separately from creation
+```
+
+### API breaking change review
+Used when: PR changes existing API endpoints or response schemas.
+Additional prompt addition:
+```
+API BREAKING CHANGE REVIEW MODE.
+Verify:
+1. Is this change documented as breaking in the PR description?
+2. Is the API version incremented appropriately?
+3. Are existing clients given a deprecation period?
+4. Is a migration guide included for API consumers?
+5. Do integration tests cover both old and new API contracts?
+```

package/.mindforge/production/compatibility-layer.md

@@ -0,0 +1,39 @@
+# MindForge Production — Cross-Version Compatibility Layer
+
+## Purpose
+Allow newer MindForge engines to operate safely against older state files
+and plugin manifests without breaking workflows or corrupting data.
+
+## Compatibility principles
+1. **Read old, write new**: old schemas must remain readable; writes should
+   upgrade only when explicitly requested (via `/mindforge:migrate`).
+2. **Never block on older schema**: warn, suggest migration, continue.
+3. **Preserve unknown fields**: never delete fields you do not recognize.
+
+## State file compatibility
+### HANDOFF.json
+- If `schema_version` is missing, treat as legacy and warn once per session.
+- If `schema_version` < current and delta > patch, suggest `/mindforge:migrate`.
+- Add default values at runtime (do not write) for missing fields.
+
+### AUDIT.jsonl
+- Treat unknown `event` types as opaque and pass through.
+- If `session_id` is missing in legacy entries, display as `unknown`.
+
+### MINDFORGE.md
+- Enforce non-overridable keys (ADR-013) regardless of file version.
+- If a setting has changed formats (e.g., percent -> decimal), prefer migration.
+
+## Plugin compatibility
+Plugin compatibility is enforced at install/validate time:
+1. `plugin_api_version` must be `1.0.0` for v1.x.x.
+2. `min_mindforge_version` must be <= current version.
+3. If incompatible, skip plugin and report to user; do not fail session start.
+
+## SDK compatibility
+- SDK clients should tolerate missing optional fields in responses.
+- New event types should be additive (never remove existing types in 1.x.x).
+
+## Version policy
+- Backwards-incompatible changes require a MAJOR bump (ADR-020).
+- Additive changes must be documented in CHANGELOG.md and reference docs.

package/.mindforge/production/migration-engine.md

@@ -0,0 +1,52 @@
+# MindForge Production — Migration Engine
+
+## Purpose
+Provide a safe, repeatable path for upgrading `.planning/` state files across
+MindForge versions without losing data or breaking governance.
+
+The migration engine is the authoritative source for state schema upgrades:
+- `HANDOFF.json`
+- `STATE.md`
+- `AUDIT.jsonl`
+- `MINDFORGE.md` (only when format changes are required)
+
+## Entry points
+- CLI: `node bin/migrations/migrate.js --from <version> --to <version>`
+- Command: `/mindforge:migrate [--from vX.Y.Z] [--to vA.B.C] [--dry-run]`
+- Update flow: `/mindforge:update --apply` (auto-runs migration)
+
+## Version chain
+Migrations are applied in order using `bin/migrations/schema-versions.js`.
+Supported range:
+- `0.1.0` -> `0.5.0`
+- `0.5.0` -> `0.6.0`
+- `0.6.0` -> `1.0.0`
+
+## Backup and recovery
+Before any migration:
+1. Create `.planning/backup-<timestamp>/`
+2. Copy `HANDOFF.json`, `STATE.md`, `AUDIT.jsonl`, `MINDFORGE.md` if present
+3. Abort if backup fails
+
+If migration fails:
+- Restore files from backup
+- Surface error with next steps
+
+## Schema version source of truth
+`HANDOFF.json.schema_version` is the authoritative indicator of state schema.
+If missing, the current package version is used as a fallback.
+
+## Safety rules
+- Never mutate or delete `.planning/` files on `--dry-run`
+- If a file is missing, skip it (do not create new state files)
+- Preserve unknown fields for forward compatibility
+
+## CI behavior
+- In CI, migrations should be non-interactive
+- Backup directories may be auto-deleted after successful migration
+  to avoid disk accumulation in shared runners
+
+## Troubleshooting
+- If a migration fails, run `/mindforge:migrate --dry-run` to inspect plan
+- If `AUDIT.jsonl` has invalid lines, they are preserved (not modified)
+- If `MINDFORGE.md` value conversion fails, the file is left unchanged

package/.mindforge/production/production-checklist.md

@@ -0,0 +1,165 @@
+# MindForge v1.0.0 — Production Readiness Checklist
+
+## Policy: ALL 55 items must be ✅ before tagging v1.0.0
+
+This is not a "should" list — it is a hard gate.
+No item can be marked ✅ without:
+1. The specific verification step executed successfully
+2. The verifier's git email recorded
+3. The date verified recorded
+
+Document completed checks in `.planning/RELEASE-CHECKLIST.md`.
+
+---
+
+## SECTION A — Installation & Upgrade (10 points)
+
+| # | Check | Verification step | ✅/❌ | Verified by | Date |
+|---|---|---|---|---|---|
+| A01 | `npx mindforge-cc@latest` launches interactive wizard on macOS | Run on macOS terminal with TTY | | | |
+| A02 | `npx mindforge-cc@latest` launches wizard on Linux | Run on Ubuntu 22.04 LTS terminal | | | |
+| A03 | `npx mindforge-cc --claude --local` installs correctly | Verify files, run /mindforge:health | | | |
+| A04 | `npx mindforge-cc --all --global` installs both runtimes | Check ~/.claude and ~/.gemini/antigravity | | | |
+| A05 | `--update` updates and preserves install scope | Install locally, run --update, verify scope preserved | | | |
+| A06 | `--uninstall` removes only MindForge files (not .planning/) | Run uninstall, verify .planning/ intact | | | |
+| A07 | `--version` and `--help` exit 0 with correct output | Run both flags, check exit code | | | |
+| A08 | Install over existing CLAUDE.md backs it up | Create custom CLAUDE.md, install, verify backup | | | |
+| A09 | Install over existing .planning/ preserves it | Create test .planning/, install, verify preserved | | | |
+| A10 | Node.js < 18 prints helpful error and exits 1 | Run with node 16, verify error message | | | |
+
+## SECTION B — Command Coverage (10 points)
+
+| # | Check | Verification step | ✅/❌ | Verified by | Date |
+|---|---|---|---|---|---|
+| B01 | `/mindforge:help` shows all 36 commands | Count commands in output, verify ≥ 36 | | | |
+| B02 | `/mindforge:init-project` creates all 5 required .planning/ files | Run in empty dir, check file list | | | |
+| B03 | `/mindforge:health` reports ✅ on a fresh install | Fresh install, run health, zero errors | | | |
+| B04 | `/mindforge:health --repair` fixes CLAUDE.md drift | Corrupt .agent/CLAUDE.md, run repair, verify fix | | | |
+| B05 | `/mindforge:skills list` shows all 10 core skills | Count in output, verify all 10 names | | | |
+| B06 | `/mindforge:skills validate` shows all valid | Run, verify zero errors | | | |
+| B07 | `/mindforge:security-scan --secrets` detects fake key | Add test key pattern, scan, verify detection | | | |
+| B08 | `/mindforge:audit --summary` shows metrics dashboard | Run in project with some audit entries | | | |
+| B09 | `/mindforge:update` checks version without changing files | Run without --apply, verify no file changes | | | |
+| B10 | `/mindforge:migrate --dry-run` shows plan without changes | Run dry-run on v0.6.0 schema, verify dry-run | | | |
+
+## SECTION C — Governance Gates (10 points)
+
+| # | Check | Verification step | ✅/❌ | Verified by | Date |
+|---|---|---|---|---|---|
+| C01 | Gate 3 (secret detection) blocks commit with fake API key | Stage file with `FAKE_ghp_abcdef1234567890abcd`, run gate | | | |
+| C02 | Gate 2 (tests passing) blocks on test failure | Break a test, run gate, verify block | | | |
+| C03 | Gate 1 (CRITICAL findings) blocks PR creation | Add CRITICAL finding to SECURITY-REVIEW, attempt ship | | | |
+| C04 | AUDIT.jsonl gains entry for every task start and complete | Execute one quick task, count new AUDIT lines | | | |
+| C05 | Tier 3 change classifier detects jwt.sign in non-auth path | Create file with jwt.sign, run classifier | | | |
+| C06 | Tier 3 CI block produces clear error message | Simulate CI run with Tier 3 pending, check output | | | |
+| C07 | MINDFORGE.md non-overridable keys are silently enforced | Set SECRET_DETECTION=false, verify it has no effect | | | |
+| C08 | Approval workflow creates APPROVAL-[uuid].json | Request a Tier 2 approval, verify file created | | | |
+| C09 | Plugin injection guard blocks malicious SKILL.md | Create SKILL.md with IGNORE ALL PREVIOUS, run guard | | | |
+| C10 | All 5 compliance gates produce GATE-RESULTS-N.md | Complete a full phase, verify GATE-RESULTS file | | | |
+
+## SECTION D — Documentation (10 points)
+
+| # | Check | Verification step | ✅/❌ | Verified by | Date |
+|---|---|---|---|---|---|
+| D01 | README.md quick start works end-to-end in < 5 minutes | New developer follows README, measures time | | | |
+| D02 | `docs/reference/commands.md` documents all 36 commands | Count documented commands, verify ≥ 36 | | | |
+| D03 | `docs/enterprise-setup.md` covers all integration steps | Walk through integration setup docs | | | |
+| D04 | `docs/governance-guide.md` explains all 3 tiers clearly | Review with someone unfamiliar with governance | | | |
+| D05 | `docs/security/threat-model.md` covers all 7 threat actors | Count actors, verify controls for each | | | |
+| D06 | `docs/security/SECURITY.md` has disclosure process | Verify email + 90-day policy present | | | |
+| D07 | `docs/contributing/CONTRIBUTING.md` has PR guidelines | Check for: fork, branch, test, PR process | | | |
+| D08 | `docs/contributing/skill-authoring.md` is actionable | Follow guide to create a test skill | | | |
+| D09 | All 20 ADRs listed in decision-records-index.md | Count ADRs, cross-check index | | | |
+| D10 | CHANGELOG.md v1.0.0 entry is complete with date | Verify entry has date, all components listed | | | |
+
+## SECTION E — Test Coverage (10 points)
+
+| # | Check | Verification step | ✅/❌ | Verified by | Date |
+|---|---|---|---|---|---|
+| E01 | All 15 test suites pass with 0 failures (Run 1) | Execute full test battery | | | |
+| E02 | All 15 test suites pass with 0 failures (Run 2) | Execute full test battery again | | | |
+| E03 | All 15 test suites pass with 0 failures (Run 3) | Execute full test battery third time | | | |
+| E04 | No test uses `process.exit(0)` inside a test function | `grep -rn 'process.exit(0)' tests/` | | | |
+| E05 | E2E tests simulate complete brownfield onboarding | Run tests/e2e.test.js, verify brownfield path | | | |
+| E06 | Migration tests cover v0.1.0 → v1.0.0 full chain | Run tests/migration.test.js full suite | | | |
+| E07 | No test has `// TODO` or `// skip` in test body | `grep -rn 'TODO\|skip' tests/` | | | |
+| E08 | Security penetration test pass (all 7 threat actors) | Run through threat-model.md controls manually | | | |
+| E09 | CI pipeline runs all tests on PR against main | Create test PR, verify CI passes | | | |
+| E10 | Version in package.json matches git tag matches npm dist | `node -e "console.log(require('./package.json').version)"` | | | |
+
+## SECTION F — Release Artifacts (5 points)
+
+| # | Check | Verification step | ✅/❌ | Verified by | Date |
+|---|---|---|---|---|---|
+| F01 | package.json version === target release version | `node -e "console.log(require('./package.json').version)"` | | | |
+| F02 | SDK package.json version matches root version | `node -e "console.log(require('./sdk/package.json').version)"` | | | |
+| F03 | Git tag v1.0.0 exists and points to correct commit | `git show v1.0.0 --no-patch` | | | |
+| F04 | CHANGELOG.md has v1.0.0 entry with today’s date | `grep -n \"1.0.0\" CHANGELOG.md` | | | |
+| F05 | `npm publish --dry-run` shows no unexpected files | Run dry-run, review output | | | |
+
+---
+
+## Checkbox summary (for quick audits)
+Use this list when you want a fast “all items present” view.
+
+- [ ] A01
+- [ ] A02
+- [ ] A03
+- [ ] A04
+- [ ] A05
+- [ ] A06
+- [ ] A07
+- [ ] A08
+- [ ] A09
+- [ ] A10
+- [ ] B01
+- [ ] B02
+- [ ] B03
+- [ ] B04
+- [ ] B05
+- [ ] B06
+- [ ] B07
+- [ ] B08
+- [ ] B09
+- [ ] B10
+- [ ] C01
+- [ ] C02
+- [ ] C03
+- [ ] C04
+- [ ] C05
+- [ ] C06
+- [ ] C07
+- [ ] C08
+- [ ] C09
+- [ ] C10
+- [ ] D01
+- [ ] D02
+- [ ] D03
+- [ ] D04
+- [ ] D05
+- [ ] D06
+- [ ] D07
+- [ ] D08
+- [ ] D09
+- [ ] D10
+- [ ] E01
+- [ ] E02
+- [ ] E03
+- [ ] E04
+- [ ] E05
+- [ ] E06
+- [ ] E07
+- [ ] E08
+- [ ] E09
+- [ ] E10
+- [ ] F01
+- [ ] F02
+- [ ] F03
+- [ ] F04
+- [ ] F05
+
+---
+
+## Release gate procedure
+
+When ALL 50 items show ✅:

package/.mindforge/production/token-optimiser.md

@@ -0,0 +1,68 @@
+# MindForge Production — Token Usage Optimiser
+
+## Purpose
+Measure, profile, and systematically reduce Claude API token consumption.
+Token efficiency impacts both cost and session quality — a session that
+exhausts its context on large file reads has less capacity for reasoning.
+
+## Token consumption model
+
+### Where tokens are spent in a typical MindForge session
+
+| Component | Typical estimate | Notes |
+|---|---|---|
+| Session startup (CLAUDE.md + ORG.md + PROJECT.md + STATE.md) | 4,000–9,000 | Fixed per session |
+| Each skill injected (full) | 2,500–6,000 | Depends on skill complexity |
+| Each skill injected (summary) | 300–600 | When > 3 skills loaded |
+| PLAN file per task | 400–1,800 | Lean plans save 800+ tokens |
+| File reading per task | 1,500–50,000 | Biggest variable cost |
+| Agent reasoning + response | 1,500–8,000 | |
+| Verify step + output | 400–1,500 | |
+
+**Note:** These are estimates based on typical MindForge projects.
+Actual values depend on file sizes, code complexity, and model verbosity.
+Run `/mindforge:tokens` to see measured estimates for your project.
+
+### Token efficiency threshold
+
+| Efficiency | Meaning | Action |
+|---|---|---|
+| > 45% | Excellent — agent spending time on reasoning and output | No action |
+| 35–45% | Good — healthy balance | No action |
+| 20–35% | Acceptable — room to optimise | Review high-cost sessions |
+| < 20% | Poor — most tokens spent on reading, not reasoning | Apply optimisations below |
+
+## Token usage logging
+
+Token profiles are written to `.planning/token-usage.jsonl`.
+All values are **estimates** (not measured) unless otherwise noted.
+Every entry must include `measured: false` to avoid confusion.
+
+### Estimation rules
+- `code_reading_tokens` = sum of file sizes read / 4
+  (Average 4 characters per token is a reasonable proxy for code.)
+- `plan_tokens` = PLAN file size / 4
+- `summary_tokens` = SUMMARY file size / 4
+- `useful_output_tokens` = sum of SUMMARY file sizes / 4
+  (SUMMARY files are the best proxy for verified output.)
+
+### Example entry
+```json
+{
+  "timestamp": "2026-03-22T08:10:00.000Z",
+  "phase": 1,
+  "plan": "02",
+  "measured": false,
+  "token_estimates": {
+    "startup": 6200,
+    "code_reading": 18400,
+    "plan": 900,
+    "summary": 600,
+    "agent_output": 4200,
+    "total": 30300
+  },
+  "useful_output_tokens": 600,
+  "efficiency": 0.20,
+  "flags": []
+}
+```