mindforge-cc 1.0.0

package/.mindforge/integrations/confluence.md

@@ -0,0 +1,27 @@
+# MindForge — Confluence Integration
+
+## Purpose
+Publish architecture snapshots, ADRs, and milestone/phase documentation to a
+ shared wiki without making Confluence the execution source of truth.
+
+## Published artifacts
+
+| MindForge artifact | Confluence target |
+|---|---|
+| `.planning/ARCHITECTURE.md` | Architecture overview page |
+| `.planning/decisions/ADR-*.md` | ADR child pages |
+| Phase verification summaries | Sprint or phase pages |
+| Milestone reports | Release or program pages |
+
+## Publishing rules
+Use update-by-title or update-by-page-ID so repeated publishes are idempotent.
+Do not create duplicate pages on re-run. If the target exists, update in place
+ and preserve the page history.
+
+## Data safety
+Confluence publishing must exclude secrets, tokens, raw audit log content, and
+ internal-only approver notes. Publish curated summaries, not raw machine state.
+
+## Failure handling
+Publishing failures are non-fatal. Log them, append a pending manual action to
+ `.planning/STATE.md`, and provide a retry command via `/mindforge:sync-confluence`.

package/.mindforge/integrations/connection-manager.md

@@ -0,0 +1,163 @@
+# MindForge Integrations — Connection Manager
+
+## Purpose
+Centralise credential handling, integration detection, health checks, retry policy,
+ and non-fatal failure handling for all external systems. Integrations consume
+ connection state from this layer; they do not manage secrets directly.
+
+## Credential storage principles
+
+### Rule 1 — Never store credentials in MindForge files
+MindForge configuration files may store base URLs, project IDs, channel IDs,
+ reviewer lists, and feature flags. They must never contain API tokens,
+ passwords, private keys, cookies, or session secrets.
+
+### Rule 2 — Use environment variables or an external secrets manager
+Supported variables:
+
+```bash
+# Jira
+JIRA_BASE_URL=https://your-org.atlassian.net
+JIRA_USER_EMAIL=engineer@your-org.com
+JIRA_API_TOKEN=stored-in-environment-only
+
+# Confluence
+CONFLUENCE_BASE_URL=https://your-org.atlassian.net/wiki
+CONFLUENCE_API_TOKEN=stored-in-environment-only
+
+# Slack
+SLACK_BOT_TOKEN=stored-in-environment-only
+SLACK_WEBHOOK_URL=stored-in-environment-only
+SLACK_CHANNEL_ID=C01234ABCDE
+
+# GitHub / GitLab
+GITHUB_TOKEN=stored-in-environment-only
+GITLAB_TOKEN=stored-in-environment-only
+```
+
+### Rule 3 — Audit only non-sensitive metadata
+AUDIT entries may contain integration name, action, status, external IDs,
+ attempt counts, and error classes. Never log raw headers, raw response bodies
+ containing secrets, or token values.
+
+## Availability detection protocol
+
+1. Check required environment variables exist.
+2. Read `.mindforge/org/integrations/INTEGRATIONS-CONFIG.md` for required
+   non-sensitive settings.
+3. Run one lightweight health check per integration.
+4. Return one of these states:
+
+| State | Meaning | Behaviour |
+|---|---|---|
+| `available` | Credentials present and health check passed | Proceed |
+| `unconfigured` | Credentials missing | Skip, log AUDIT |
+| `invalid_credentials` | Auth failed with 401/403 | Warn, log AUDIT, stop retries |
+| `unreachable` | DNS, timeout, or 5xx | Retry up to policy, then warn |
+| `rate_limited` | 429 | Respect `Retry-After`, retry once, then stop |
+
+Missing credentials are usually a graceful skip. Exception: if a CRITICAL
+ security finding notification cannot be delivered because Slack is unconfigured,
+ write an `Undelivered alerts` section to `.planning/STATE.md` and surface it in
+ `/mindforge:status`.
+
+## Credential hygiene in shell operations
+
+### Preventing token exposure in shell history
+Avoid inline command substitution with secrets. Prefer a function or a temporary
+ client-supported credential source:
+
+```bash
+build_auth_header() {
+  printf '%s' "${1}:${2}" | base64
+}
+AUTH_HEADER=$(build_auth_header "${JIRA_USER_EMAIL}" "${JIRA_API_TOKEN}")
+```
+
+Unset secrets after the command sequence completes:
+
+```bash
+unset JIRA_API_TOKEN
+unset GITHUB_TOKEN
+unset SLACK_BOT_TOKEN
+```
+
+### Debug mode prohibition
+Never run credential-bearing commands with shell tracing enabled:
+
+```bash
+set +x
+# credential operations
+```
+
+If debugging is needed elsewhere, disable tracing before any command that
+ includes an Authorization header or secret-bearing environment variable.
+
+### curl verbose mode prohibition
+Never use `curl -v` or `curl --verbose` with authenticated requests. Capture the
+ HTTP status code with `-s -o response.json -w "%{http_code}"` and log only
+ sanitised error summaries.
+
+## Health check examples
+
+### Jira
+```bash
+HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+  -H "Authorization: Basic ${AUTH_HEADER}" \
+  "${JIRA_BASE_URL}/rest/api/3/myself")
+```
+
+### Slack
+Use `auth.test`. If the configured `SLACK_CHANNEL_ID` returns `channel_not_found`
+ or a 404-equivalent API error, mark the channel configuration invalid and tell
+ the user to update `INTEGRATIONS-CONFIG.md`.
+
+### GitHub
+Use `GET /user` with the token. A 404 from branch protection lookup later is not
+ a connection error; it means no branch protection is configured.
+
+## Credential rotation detection
+If a previously available integration now returns 401/403:
+
+1. Write AUDIT entry: `integration_credential_expired`
+2. Warn the user to rotate the relevant credential
+3. Do not retry with the expired credential
+
+## Integration resilience: shared patterns for all integrations
+
+### Non-fatal integration failures
+Integration failures must never fail the underlying source-code task. They are
+ non-fatal unless a compliance gate or required approval is blocked.
+
+### Retry policy
+
+| Attempt | Delay |
+|---|---|
+| 1 | immediate |
+| 2 | 5 seconds |
+| 3 | 20 seconds |
+
+After the third failure:
+1. Log an `integration_action` AUDIT entry with `"status": "failed"` and
+   `"attempts": 3`
+2. Add an item to `.planning/STATE.md` under `Pending integration actions`
+3. Provide the manual retry command, for example `/mindforge:sync-jira --phase 3`
+
+For 429 responses, obey `Retry-After` when present. If a second 429 occurs,
+ stop, log it, and do not retry again.
+
+## Integration action logging
+Every sync, publish, notify, approval, or PR operation writes an AUDIT entry:
+
+```json
+{
+  "id": "uuid-v4",
+  "timestamp": "ISO-8601",
+  "event": "integration_action",
+  "integration": "jira|confluence|slack|github|gitlab",
+  "action": "create_ticket|publish_page|send_notification|create_pr",
+  "status": "success|failed|skipped",
+  "detail": "brief description",
+  "external_id": "service-specific ID"
+}
+```

package/.mindforge/integrations/github.md

@@ -0,0 +1,25 @@
+# MindForge — GitHub Integration
+
+## Purpose
+Strengthen shipping with PR templates, reviewer assignment guidance, branch
+ protection awareness, and release metadata checks.
+
+## API policy
+Use GitHub REST API v3 for all required operations. GraphQL is optional for
+ advanced queries only and is not required for Day 4.
+
+## Pre-flight checks
+
+1. Verify the branch has at least one commit ahead of base:
+   `git log origin/${GITHUB_DEFAULT_BRANCH}..HEAD --oneline | wc -l`
+2. Query branch protection:
+   `GET /repos/{owner}/{repo}/branches/{branch}/protection`
+3. Treat HTTP 404 from the protection endpoint as `no branch protection
+   configured`, not as a connection failure.
+
+If there are zero commits ahead of base, do not attempt PR creation.
+
+## PR creation guidance
+Use `.github/pull_request_template.md` when present, assign default reviewers
+ from config, and ensure the PR body links verification artifacts and the
+ relevant phase or milestone documents.

package/.mindforge/integrations/gitlab.md

@@ -0,0 +1,13 @@
+# MindForge — GitLab Integration
+
+## Purpose
+Provide GitLab parity for merge request creation, reviewer defaults, and branch
+ policy awareness when GitHub is not the source control platform.
+
+## Scope
+Day 4 covers configuration and process guidance only:
+- read project and reviewer metadata from `INTEGRATIONS-CONFIG.md`
+- create merge requests with milestone or phase summaries
+- treat integration failures as non-fatal
+
+Full API parity with GitHub can be extended in later milestones.

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.