mindforge-cc 11.3.0 → 11.4.0

package/.mindforge/integrations/jira.md

@@ -0,0 +1,102 @@
+# MindForge — Jira Integration
+
+## Purpose
+Synchronise MindForge planning state into Jira for organisational visibility
+ while keeping MindForge as the source of truth for technical execution.
+
+## Mapping model
+
+| MindForge artifact/event | Jira representation |
+|---|---|
+| Phase N | Epic |
+| `PLAN-N-M.md` | Story |
+| `task_started` | Story transition to In Progress |
+| `task_completed` | Story transition to Done |
+| `task_failed` | Story comment + blocked transition when available |
+| `security_finding` HIGH/CRITICAL | Bug with security labels |
+| Phase verified | Epic transitioned to Ready for Review |
+| UAT signed off | Epic transitioned to Done |
+
+Jira-to-MindForge state ingestion is out of scope for Day 4. MindForge is the
+ source of truth; Jira reflects it.
+
+## API and authentication
+Use Jira REST API v3. Read credentials through `connection-manager.md`.
+Do not log tokens, auth headers, or raw credential-bearing commands.
+
+## Epic creation
+Create one Epic per phase. Verify the Epic Name field ID in your Jira instance
+ with `GET /rest/api/3/field` and locate `Epic Name`; do not assume
+ `customfield_10014` is universal.
+
+## Story creation
+Project type matters:
+
+- Team-managed / next-gen projects: link with `parent.key`
+- Company-managed / classic projects: use the Epic-link custom field discovered
+  from `GET /rest/api/3/field`
+
+## Dynamic transition ID lookup
+Never hardcode transition IDs. Before transitioning an issue, fetch available
+ transitions from `GET /rest/api/3/issue/{issueKey}/transitions` and match by
+ transition name.
+
+MindForge event to transition-name mapping:
+
+| Event | Preferred Jira transition name | Notes |
+|---|---|---|
+| `task_started` | `In Progress` | common default |
+| `task_completed` | `Done` | sometimes `Resolve Issue` or `Close Issue` |
+| `task_failed` | `On Hold` | fallback to `Blocked` if present |
+| `UAT_signed_off` | `Done` | used for epics |
+
+If the transition name is unavailable:
+1. Log a `sync_warning` AUDIT entry
+2. Skip the transition
+3. Never fail the source task because Jira workflow names differ
+
+Cache resolved transition IDs in `.planning/jira-sync.json` by project key.
+Refresh the cache if a transition returns 400.
+
+## Security bug creation
+When a `security_finding` has `HIGH` or `CRITICAL` severity, create a Bug with
+ the OWASP category, file, line, and remediation summary.
+
+## Conflict handling
+Preserve manual Jira edits. Sync may add comments, labels, or new issues, but
+ it must not destructively overwrite manual Jira changes.
+
+## Rate limiting and backoff
+Maintain at least 200 ms between normal calls. For batches larger than 10
+ tickets, start exponential backoff at 500 ms. On 429, respect `Retry-After`
+ and retry once; on a second 429, stop and log the failure.
+
+## Sync state file
+Track mappings in `.planning/jira-sync.json`:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "last_sync": "ISO-8601",
+  "project_key": "ENG",
+  "phase_mappings": {
+    "1": {
+      "epic_key": "ENG-42",
+      "story_keys": { "01": "ENG-43" }
+    }
+  },
+  "transition_cache": {
+    "ENG": {
+      "in_progress_id": "21",
+      "done_id": "31",
+      "blocked_id": "41",
+      "cached_at": "ISO-8601"
+    }
+  },
+  "_warning": "Do not store credentials in this file."
+}
+```
+
+`jira-sync.json` contains project metadata, not credentials, but it may expose
+ internal project structure. Consider gitignoring it in public/open-source
+ distributions.

package/.mindforge/integrations/slack.md

@@ -0,0 +1,41 @@
+# MindForge — Slack Integration
+
+## Purpose
+Send operational notifications for phase completion, blockers, security events,
+ milestone completion, and approvals.
+
+## Supported notifications
+
+| Event | Behaviour |
+|---|---|
+| phase complete | Send summary notification |
+| security finding HIGH/CRITICAL | Send urgent alert and optional mention |
+| approval needed | Post request summary with approval file reference |
+| blocker added | Post concise blocker notice |
+| milestone complete | Post release summary |
+
+## Message safety
+Sanitise all dynamic values inserted into JSON payloads. Escape double quotes,
+ backslashes, and newlines before building Block Kit payloads. Never use
+ `curl -v` with Slack tokens.
+
+## Thread management
+Store thread references in `.planning/slack-threads.json`:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "channel_id": "C01234ABCDE",
+  "threads": {
+    "phase-1": "1710931200.123456"
+  },
+  "_warning": "Do not store tokens in this file."
+}
+```
+
+If Slack rejects an existing `thread_ts`, clear that entry and create a new
+ thread instead of retrying the invalid timestamp.
+
+## Undelivered critical alerts
+If Slack is unconfigured or the channel is invalid during a CRITICAL security
+ event, write the alert into `.planning/STATE.md` under `Undelivered alerts`.

package/.mindforge/intelligence/antipattern-detector.md

@@ -0,0 +1,75 @@
+# MindForge Intelligence — Anti-Pattern Detection Engine
+
+## Purpose
+Detect architecture, database, security, code-quality, and testing anti-patterns
+at plan, execute, and review checkpoints.
+
+## Key patterns
+- A01 God object / service
+- A02 Circular dependencies
+- A03 Distributed monolith
+- A04 Hardcoded configuration
+- B01 `SELECT *`
+- B02 Missing FK indexes
+- B03 Unbounded queries
+- C01 Auth bypass via type coercion
+- C02 Missing authorization
+- C03 Sensitive data in URL
+- D01 Callback/pyramid complexity
+- D02 Magic strings
+- D03 Swallowed errors
+- E01 Tests tied to internals
+- E02 Flaky test indicators
+
+## C01 false positive prevention
+Exclude from C01 scanning:
+```bash
+grep -rn "==\s*null\|==\s*undefined\|==\s*false\|==\s*0" src/ \
+  --include="*.ts" --include="*.js" \
+  --exclude="*.test.ts" --exclude="*.spec.ts" --exclude="*.test.js" --exclude="*.spec.js"
+```
+
+Do not flag:
+- assertions in test files (`tests/**`, `*.test.*`, `*.spec.*`)
+- intentional type-guard nullish checks (`x == null`) in type-guard functions
+
+Only treat C01 as critical in auth/middleware/security-sensitive paths.
+
+## B03 cursor pagination exception
+Cursor-based pagination is exempt from unbounded query check.
+Recognize exemptions:
+- Prisma `cursor:` parameter
+- query with both `orderBy:` and `cursor:`
+- SQL tuple cursor predicates (`WHERE (..., ...) < (..., ...)`)
+
+```bash
+grep -rn "findMany\\b" src/ --include="*.ts" | python3 - <<'PY'
+import sys
+for line in sys.stdin:
+    l = line.lower()
+    if 'cursor:' in l or '< :cursor' in l or '<(' in l:
+        continue
+    if 'take:' not in l and 'limit:' not in l:
+        print('B03 candidate:', line.strip())
+PY
+```
+
+## D01 executable line counting
+Use executable-line heuristic for God-object thresholding, not raw `wc -l`.
+
+```bash
+count_executable_lines() {
+  local f="$1"
+  grep -v '^\s*$' "$f" | grep -v '^\s*//' | grep -v '^\s*\*' | grep -v '^\s*@' | wc -l
+}
+```
+
+Apply threshold to executable count (e.g., `>500`) plus dependency fan-in signal.
+
+## Trigger points
+- Plan phase: architecture patterns (A*)
+- Execute phase: implementation/security patterns (B*, C*, D03)
+- Review phase: full library
+
+## Report format
+Include id, severity, location, and exact remediation advice.

package/.mindforge/intelligence/difficulty-scorer.md

@@ -0,0 +1,55 @@
+# MindForge Intelligence — Phase Difficulty Scorer
+
+## Purpose
+Score phase complexity before planning so decomposition and verification rigor
+match risk.
+
+## Dimensions
+- Technical complexity (35%)
+- Risk level (30%)
+- Ambiguity (20%)
+- Dependencies (15%)
+
+Composite:
+`(Technical*0.35) + (Risk*0.30) + (Ambiguity*0.20) + (Dependencies*0.15)`
+
+## Signal detection
+### Technical complexity context handling
+Keyword matching must include local context windows.
+
+- `migration` near `database` or `schema` => technical `4`
+- `migration` near `code` or `framework` => technical `3`
+
+### Risk amplifiers
+Add +1 for each relevant amplifier (cap 5):
+- missing test baseline in touched area
+- external integration without sandbox
+- shared module blast radius (`>3` consumers)
+- unclear rollback path
+- prior related incidents
+
+For prior incidents, inspect `AUDIT.jsonl`:
+- `task_failed` events with file-path overlap with expected touched files
+- `security_finding` events in overlapping domains (auth/payments/database)
+
+## Score bands
+- `1.0-2.0` Easy => `2-3` tasks
+- `2.1-3.0` Moderate => `4-6` tasks
+- `3.1-4.0` Challenging => `6-10` tasks
+- `4.1-5.0` Hard => `10-15` tasks
+
+If composite `> 4.5`: recommend split into `Phase N-A` (lowest-risk)
+and `Phase N-B` (highest-risk), and offer:
+`/mindforge:discuss-phase [N] --split`
+
+## Feedback loop: score -> granularity
+The planner must read `DIFFICULTY-SCORE-[N].md` before creating plans.
+
+| Composite | Granularity instruction |
+|---|---|
+| 1.0-2.0 | 1 task = complete feature component |
+| 2.1-3.0 | 1 task = significant module/function |
+| 3.1-4.0 | 1 task = specific function/endpoint |
+| 4.1-5.0 | 1 task = narrow change in 3-4 files max |
+
+This creates explicit feedback: difficulty -> decomposition -> execution quality.

package/.mindforge/intelligence/health-engine.md

@@ -0,0 +1,208 @@
+# MindForge Intelligence — Health Engine
+
+## Purpose
+Run a comprehensive health check across installation, context, skills, personas,
+state, integrations, and security. Detect drift and provide safe auto-repair.
+
+## Categories
+1. Installation integrity
+2. Context file health
+3. Skills registry health
+4. Persona system health
+5. State consistency
+6. Integration connectivity
+7. Security configuration
+
+## Category 1 — Installation integrity
+
+### Required files checklist
+```bash
+REQUIRED_FILES=(
+  ".claude/CLAUDE.md"
+  ".agent/CLAUDE.md"
+
+  ".claude/commands/mindforge/help.md"
+  ".claude/commands/mindforge/init-project.md"
+  ".claude/commands/mindforge/plan-phase.md"
+  ".claude/commands/mindforge/execute-phase.md"
+  ".claude/commands/mindforge/verify-phase.md"
+  ".claude/commands/mindforge/ship.md"
+  ".claude/commands/mindforge/next.md"
+  ".claude/commands/mindforge/quick.md"
+  ".claude/commands/mindforge/status.md"
+  ".claude/commands/mindforge/debug.md"
+  ".claude/commands/mindforge/skills.md"
+  ".claude/commands/mindforge/review.md"
+  ".claude/commands/mindforge/security-scan.md"
+  ".claude/commands/mindforge/map-codebase.md"
+  ".claude/commands/mindforge/discuss-phase.md"
+  ".claude/commands/mindforge/audit.md"
+  ".claude/commands/mindforge/milestone.md"
+  ".claude/commands/mindforge/complete-milestone.md"
+  ".claude/commands/mindforge/approve.md"
+  ".claude/commands/mindforge/sync-jira.md"
+  ".claude/commands/mindforge/sync-confluence.md"
+  ".claude/commands/mindforge/health.md"
+  ".claude/commands/mindforge/retrospective.md"
+  ".claude/commands/mindforge/profile-team.md"
+  ".claude/commands/mindforge/metrics.md"
+
+  ".mindforge/engine/wave-executor.md"
+  ".mindforge/engine/dependency-parser.md"
+  ".mindforge/engine/context-injector.md"
+  ".mindforge/engine/compaction-protocol.md"
+  ".mindforge/engine/verification-pipeline.md"
+  ".mindforge/engine/skills/registry.md"
+  ".mindforge/engine/skills/loader.md"
+  ".mindforge/engine/skills/versioning.md"
+  ".mindforge/engine/skills/conflict-resolver.md"
+
+  ".mindforge/skills/security-review/SKILL.md"
+  ".mindforge/skills/code-quality/SKILL.md"
+  ".mindforge/skills/api-design/SKILL.md"
+  ".mindforge/skills/testing-standards/SKILL.md"
+  ".mindforge/skills/documentation/SKILL.md"
+  ".mindforge/skills/performance/SKILL.md"
+  ".mindforge/skills/accessibility/SKILL.md"
+  ".mindforge/skills/data-privacy/SKILL.md"
+  ".mindforge/skills/incident-response/SKILL.md"
+  ".mindforge/skills/database-patterns/SKILL.md"
+
+  ".mindforge/personas/analyst.md"
+  ".mindforge/personas/architect.md"
+  ".mindforge/personas/developer.md"
+  ".mindforge/personas/qa-engineer.md"
+  ".mindforge/personas/security-reviewer.md"
+  ".mindforge/personas/tech-writer.md"
+  ".mindforge/personas/debug-specialist.md"
+  ".mindforge/personas/release-manager.md"
+
+  ".mindforge/intelligence/health-engine.md"
+  ".mindforge/intelligence/difficulty-scorer.md"
+  ".mindforge/intelligence/antipattern-detector.md"
+  ".mindforge/intelligence/skill-gap-analyser.md"
+  ".mindforge/intelligence/smart-compaction.md"
+
+  ".mindforge/governance/change-classifier.md"
+  ".mindforge/governance/approval-workflow.md"
+  ".mindforge/governance/compliance-gates.md"
+
+  ".mindforge/org/ORG.md"
+  ".mindforge/org/CONVENTIONS.md"
+  ".mindforge/org/SECURITY.md"
+  ".mindforge/org/TOOLS.md"
+  ".mindforge/org/skills/MANIFEST.md"
+  ".mindforge/org/integrations/INTEGRATIONS-CONFIG.md"
+
+  ".planning/HANDOFF.json"
+  ".planning/STATE.md"
+  ".planning/AUDIT.jsonl"
+)
+```
+
+`MINDFORGE.md` is optional and is not in required files.
+If `MINDFORGE.md` exists, validate:
+- no unknown skills (must exist in `.mindforge/org/skills/MANIFEST.md`)
+- no invalid model names (fallback to `inherit` + warning)
+- no attempted overrides of governance primitives
+
+### Version check
+- Validate `package.json` semver is `>= 0.5.0`.
+
+### CLAUDE parity
+- `.claude/CLAUDE.md` and `.agent/CLAUDE.md` must be identical.
+- All commands under `.claude/commands/mindforge/` must exist in `.agent/mindforge/`.
+
+## Category 2 — Context file health
+- `PROJECT.md` has tech stack, v1 scope, success criteria, and no placeholders.
+- `REQUIREMENTS.md` has FR entries with acceptance criteria and scope tags.
+- `STATE.md` has recent `Last updated` timestamp and coherent status.
+- `HANDOFF.json` is valid JSON with required fields and no secrets.
+- `ARCHITECTURE.md` exists with stack and decision references.
+
+## Category 3 — Skills registry health
+- `MANIFEST.md` exists; all 10 core skills listed with valid semver.
+- Every manifest skill path exists.
+- Every `SKILL.md` includes frontmatter: `name`, `version`, `status`, `triggers`.
+- Trigger conflict check runs and reports count.
+
+## Category 4 — Persona system health
+- Each persona has Identity, Pre-task checklist, Escalation, DoD.
+- Persona files are non-stub (>500 bytes).
+- Override files contain no prompt-injection markers.
+
+## Category 5 — State consistency
+- For every phase in ROADMAP: directory + required artifacts match phase status.
+- Explicit check: if `STATE.md` marks phase complete and summaries exist but `VERIFICATION.md` is missing, flag as error.
+- `AUDIT.jsonl` lines parse as JSONL and timestamps are chronological.
+- Commit hygiene:
+  - conventional commit format in recent history
+  - on `main`, only flag commits whose subject starts with `wip` (case-insensitive)
+
+## Category 6 — Integration connectivity
+For configured integrations, run lightweight auth checks and report:
+- `available`
+- `invalid_credentials`
+- `unreachable`
+- `unconfigured` (informational only)
+
+## Category 7 — Security configuration
+- `.gitignore` covers env files and keys.
+- Secret scan covers:
+  - `.planning/`
+  - `.mindforge/`
+  - root-level `MINDFORGE.md`, `.env.example`, `*.config.js`
+- `SECURITY.md` has no placeholders.
+- Governance approval files are not stale beyond SLA.
+
+## Auto-repair protocol
+
+### Auto-repairable
+- sync `.agent/CLAUDE.md` from `.claude/CLAUDE.md`
+- mirror missing command files from `.claude` to `.agent`
+- add missing `Last updated` in `STATE.md`
+- create `.planning/approvals/` if missing
+- mark expired approvals and audit them
+- trigger AUDIT archive protocol when threshold exceeded
+
+### AUDIT.jsonl corruption handling (updated)
+**Never delete lines from `AUDIT.jsonl`.**
+
+```bash
+python3 - <<'PY'
+import json
+from pathlib import Path
+
+audit = Path('.planning/AUDIT.jsonl')
+if not audit.exists():
+    raise SystemExit(0)
+
+invalid = []
+for i, raw in enumerate(audit.read_text().splitlines(), 1):
+    s = raw.strip()
+    if not s:
+        continue
+    try:
+        json.loads(s)
+    except Exception:
+        invalid.append({"line": i, "raw": s})
+
+if invalid:
+    qf = Path('.planning/AUDIT.jsonl.quarantine')
+    with qf.open('a', encoding='utf-8') as f:
+        for row in invalid:
+            f.write(json.dumps(row) + "\n")
+    print(f"Quarantined {len(invalid)} invalid lines to {qf}")
+PY
+
+echo "{\"event\":\"audit_quarantine\",\"quarantine_file\":\".planning/AUDIT.jsonl.quarantine\"}" >> .planning/AUDIT.jsonl
+```
+
+### Non-auto-repairable
+- missing core skill files
+- invalid credentials
+- secrets found in `HANDOFF.json`
+- prompt-injection patterns in persona overrides
+
+## Health report format
+Provide summary by category with errors, warnings, info, and exact next fixes.

package/.mindforge/intelligence/skill-gap-analyser.md

@@ -0,0 +1,40 @@
+# MindForge Intelligence — Skill Gap Analyser
+
+## Purpose
+Identify required/recommended skills for a phase, compare with installed
+skills, and report gaps before planning.
+
+## Run points
+1. `/mindforge:plan-phase` start
+2. `/mindforge:discuss-phase`
+3. `/mindforge:health`
+
+## Analysis flow
+1. Extract work signals from roadmap/context/requirements/architecture.
+2. Map work categories to required/recommended skills.
+3. Validate skills in manifest + filesystem + status.
+4. Report missing/deprecated required skills and mitigation options.
+
+## Category -> skill mapping
+- UI/UX -> accessibility (required), performance (recommended)
+- Database changes -> database-patterns (required), data-privacy (if PII)
+- API endpoints -> api-design (required), security-review (if auth)
+- Auth/payments/PII -> security-review (required), data-privacy (required for PII)
+- Performance work -> performance (required)
+- New feature -> testing-standards (required), documentation (recommended)
+
+## Gap definition
+A required skill is a gap if:
+- not present in MANIFEST
+- manifest path missing
+- marked deprecated with no replacement
+
+## Output
+Produce `Skill Gap Analysis` section with:
+- required skills table
+- recommended skills table
+- explicit gap count and options
+
+## Health mode
+In `/mindforge:health`, include org-level recommendation list using recent
+phase patterns and missing capability frequencies.

package/.mindforge/intelligence/smart-compaction.md

@@ -0,0 +1,71 @@
+# MindForge Intelligence — Smart Context Compaction
+
+## Purpose
+Replace truncation with structured extraction so future sessions preserve reasoning,
+constraints, and in-progress state.
+
+## Triggering and level selection
+Day 2 threshold (`70%`) remains valid and now invokes Day 5 Level 1.
+Level selection uses both context usage and session depth.
+
+- Light session (`<5` tasks): use Level 1 even when context is high.
+- Moderate session (`5-10` tasks): use Level 2 at `80%+`.
+- Deep session (`10+` tasks): use Level 2 at `75%+`.
+- Level 3 at `90%+` or urgent near-limit state.
+
+## Levels
+### Level 1 — Lightweight
+Quick checkpoint: update `STATE.md` and `HANDOFF.json` with next task.
+
+### Level 2 — Structured extraction
+Capture:
+- decisions made
+- discoveries
+- implicit knowledge
+- quality signals
+- precise in-progress state
+
+### Level 3 — Emergency extraction
+Capture minimum viable continuation context before hard limit.
+
+## Level 2 extraction protocol
+### Block A — Decisions made
+For each decision: what, why, alternatives ruled out, impact area, ADR need.
+
+### Block B — Discoveries
+For each finding: fact, location, significance, assumption impact.
+
+### Block C — Current task state
+Record plan id, completed steps, remaining steps, current file, and inconsistency state.
+
+### Block D — Implicit knowledge
+Capture quirks, environment facts, and workarounds.
+
+A knowledge item qualifies as a **quirk** if either:
+1. It contradicts documentation or expected tool behavior.
+2. A new agent reading only plans/personas would not infer it.
+
+### Block E — Quality signals
+Capture failed assumptions, friction patterns, quality gate root causes, and next-plan suggestions.
+
+## Level 2 HANDOFF schema additions
+- `decisions_made[]`
+- `discoveries[]`
+- `implicit_knowledge[]`
+- `quality_signals[]`
+- `in_progress.current_state`
+
+## Session restart protocol
+When loading Level 2 handoff:
+1. Print compact summary counts.
+2. Preload `implicit_knowledge` before plan execution.
+3. If `in_progress.current_state` is inconsistent, block execution and ask to resolve first.
+4. If user asks to inspect first, print first 50 lines of the inconsistent file inline.
+
+## Compaction quality metric
+Write one entry to `.mindforge/metrics/compaction-quality.jsonl`:
+- `decisions_captured`
+- `discoveries_captured`
+- `implicit_knowledge_items`
+- `quality_signals_captured`
+- `next_session_continuation_success` (auto-inferred from next session, nullable initially)