mindforge-cc 11.3.0 → 11.4.0

package/.claude/commands/mindforge/workstreams.md

@@ -0,0 +1,35 @@
+---
+name: "mindforge:workstreams"
+description: "Manage parallel feature tracks with isolated state"
+argument-hint: [list|create|switch|status|complete]
+allowed-tools:
+  - list_dir
+  - view_file
+  - write_to_file
+  - run_command
+---
+
+<objective>
+Enable developers to work on multiple features or bugs concurrently within the same codebase without state collision. Provides isolated tracking for each "workstream".
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/workstreams.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (Switch subcommand)
+Storage: .planning/workstreams/
+State: Each workstream maintains its own subset of `STATE.md` or a local context file.
+</context>
+
+<process>
+1. **Route Subcommand**:
+    - `list`: Show all active and archived workstreams in `.planning/workstreams/`.
+    - `create <name>`: Initialize a new workstream directory and baseline state.
+    - `switch <name>`: Update the global pointer in `STATE.md` to the targeted workstream.
+    - `status`: Show the current active workstream and its progress.
+2. **Manage Isolation**:
+    - When switching, ensure current work is saved or stashed if necessary.
+3. **Confirm**: Success/Failure status message to user.
+</process>

package/.claude/commands/mindforge/worktrees.md

@@ -0,0 +1,86 @@
+---
+description: "Manage parallel git worktrees for isolated concurrent work. Usage: /mindforge:worktrees [create|list|remove|cleanup] [--name feature-name]"
+---
+
+<objective>
+Manage git worktrees to enable parallel, isolated development streams — creating, listing, removing, and cleaning up worktrees with proper branch hygiene and state management.
+</objective>
+
+<execution_context>
+@.mindforge/skills/using-git-worktrees/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (action: create|list|remove|cleanup, optional --name for branch/worktree name)
+Knowledge: Current git state, active branches, remote tracking status, .planning/STATE.md.
+</context>
+
+<process>
+1. **Parse action**: Determine the requested operation:
+   - `create` — Create a new worktree with an associated branch
+   - `list` — Show all active worktrees with status
+   - `remove` — Remove a specific worktree and optionally its branch
+   - `cleanup` — Find and remove stale/orphaned worktrees
+   - If no action specified, default to `list`
+
+2. **Verify branch availability** (for create):
+   - Check if --name branch already exists locally or remotely
+   - If exists locally: offer to reuse or create with suffix
+   - If exists remotely but not locally: offer to track
+   - If doesn't exist: proceed with creation
+   - Validate branch name follows conventions (feat/, fix/, etc.)
+
+3. **Execute worktree operation**:
+   - **create**: `git worktree add ../[repo]-[name] -b [branch-name] [base-branch]`
+     - Base branch defaults to main/master unless specified
+     - Worktree directory placed adjacent to main repo
+     - Copy relevant config files (.env.local, .tool-versions) if they exist
+   - **list**: `git worktree list --porcelain` parsed into readable table
+   - **remove**: `git worktree remove [path]` with force flag if dirty
+   - **cleanup**: `git worktree prune` + scan for orphaned directories
+
+4. **Confirm isolation**: After create, verify the worktree is properly isolated:
+   - Confirm separate working directory exists
+   - Confirm branch is checked out in new worktree
+   - Confirm no shared lock files between worktrees
+   - Verify node_modules/venv are independent (or symlinked appropriately)
+   - Run basic sanity check (git status in new worktree shows clean state)
+
+5. **Setup worktree environment** (for create):
+   - Install dependencies if package manager lockfile exists
+   - Copy local-only config (.env.local, .env.development.local)
+   - Initialize any required local state (database migrations, etc.)
+   - Set up IDE/editor workspace if workspace files exist
+
+6. **Report status**: Output clear status information:
+   - For `list`: Table with columns [Path | Branch | Last Commit | Status (clean/dirty)]
+   - For `create`: Full path to new worktree, branch name, base commit
+   - For `remove`: Confirmation of removal, whether branch was also deleted
+   - For `cleanup`: Count of pruned worktrees, freed disk space estimate
+
+7. **Cleanup stale worktrees** (for cleanup action):
+   - Run `git worktree prune` to remove references to deleted directories
+   - Scan for worktree directories that still exist but have no matching git reference
+   - Identify branches associated with merged PRs (safe to remove)
+   - Present list for user confirmation before deletion
+   - Remove node_modules/build artifacts in stale worktrees to free space
+
+8. **Update MindForge state**: Record worktree operations:
+   - Log active worktrees in `.planning/WORKTREES.md`
+   - Track which task/phase each worktree is associated with
+   - Note creation date and last activity date
+   - Flag worktrees inactive for >7 days as candidates for cleanup
+
+9. **Handle edge cases**:
+   - Worktree on a branch that was force-pushed: detect and offer rebase
+   - Worktree with uncommitted changes on remove: warn and require --force
+   - Maximum worktree count (suggest limit of 5 to avoid confusion)
+   - Disk space check before creating (warn if <2GB available)
+
+10. **Output helper commands**: Provide convenience shortcuts:
+    - Command to cd into the new worktree
+    - Command to open worktree in new editor window
+    - Command to run tests in the worktree
+    - Reminder of how to switch back to main worktree
+    - Git commands for merging worktree branch back
+</process>

package/.claude/commands/mindforge/write-rfc.md

@@ -0,0 +1,64 @@
+---
+description: "Author technical RFC or design document. Usage: /mindforge:write-rfc [title] [--template rfc|adr|design-doc|runbook]"
+---
+
+<objective>
+Author a structured technical RFC or design document using the appropriate template, written for a cold reader with code examples and clear trade-off analysis.
+</objective>
+
+<execution_context>
+@.mindforge/skills/technical-writing/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (document title, optional --template rfc|adr|design-doc|runbook)
+Knowledge: Current architecture, existing RFCs/ADRs, team conventions, technical constraints.
+</context>
+
+<process>
+1. **Select template**: Based on --template flag or document purpose:
+   - **RFC**: Full proposal for significant system changes (new service, protocol change, major refactor)
+   - **ADR**: Concise architectural decision record (single decision with context and consequences)
+   - **Design Doc**: Detailed technical design for a feature (implementation-focused)
+   - **Runbook**: Operational procedure for handling incidents or maintenance tasks
+   - Each template has a defined structure — never deviate from it
+
+2. **Fill structure**: Populate the selected template:
+   - **RFC structure**: Title → Status (Draft/Proposed/Accepted/Rejected) → Summary (2-3 sentences) → Motivation (why now, what problem) → Detailed Design (how it works) → Drawbacks (honest downsides) → Alternatives Considered (what else was evaluated) → Open Questions (unresolved decisions) → References
+   - **ADR structure**: Title → Date → Status → Context (forces at play) → Decision (what we chose) → Consequences (positive, negative, neutral)
+   - **Design Doc structure**: Title → Authors → Reviewers → Summary → Background → Goals/Non-Goals → Design → Implementation Plan → Testing Strategy → Rollout Plan → Monitoring → Open Questions
+   - **Runbook structure**: Title → When to Use → Prerequisites → Steps (numbered, exact commands) → Verification → Rollback → Escalation → Post-Incident
+
+3. **Write for cold reader**: Ensure accessibility:
+   - Define all acronyms on first use
+   - Provide context before technical details (why before how)
+   - Use diagrams to explain complex flows (ASCII art or description)
+   - Link to relevant existing documentation (don't repeat, reference)
+   - Write in active voice, present tense
+   - One idea per paragraph, one decision per section
+   - Assume the reader has general engineering knowledge but no project-specific context
+
+4. **Add code examples**: Include concrete implementations:
+   - Minimal working examples (not pseudocode — real, runnable code)
+   - API usage examples showing request and response
+   - Configuration snippets with comments explaining each field
+   - Error handling examples (not just happy path)
+   - Before/after comparisons for migration-type changes
+   - Keep examples short (< 30 lines) — link to full implementation if longer
+
+5. **Review completeness**: Validate the document:
+   - Does the Summary stand alone? (reader should understand the proposal from Summary only)
+   - Are all trade-offs honestly stated? (no strawman alternatives)
+   - Are success criteria defined? (how do we know this worked?)
+   - Are failure modes addressed? (what if this goes wrong?)
+   - Is the scope clear? (what is explicitly NOT covered?)
+   - Are dependencies identified? (what must exist before this can proceed?)
+   - Is there a timeline? (when should this be decided/implemented?)
+
+6. **Submit for feedback**: Prepare for review:
+   - Identify reviewers (domain experts, stakeholders, implementers)
+   - Highlight open questions that need input
+   - Set review deadline (1 week for RFC, 3 days for ADR)
+   - Define approval criteria (who must approve, what constitutes consensus)
+   - Output the complete document in the appropriate location (.planning/rfcs/ or .planning/decisions/)
+</process>

package/.claude/commands/mindforge/zero-trust.md

@@ -0,0 +1,34 @@
+---
+name: "mindforge:zero-trust"
+description: "Design zero-trust network architecture. Usage: /mindforge:zero-trust [system] [--scope internal|external|both] [--mtls]"
+argument-hint: "[system] [--scope internal|external|both] [--mtls]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design a zero-trust network architecture that eliminates implicit trust, enforces continuous verification for every communication flow, and implements micro-segmentation with identity-based access control.
+</objective>
+
+<execution_context>
+@.mindforge/skills/zero-trust-architecture/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/zero-trust-architecture/`
+State: Inventories all system communication flows and applies identity verification, mTLS, and micro-segmentation policies.
+</context>
+
+<process>
+1. **Inventory All Communication Flows**: Map every service-to-service, user-to-service, and external integration communication path. Include direction, protocol, port, and data sensitivity classification.
+2. **Classify by Sensitivity**: Assign trust tiers (critical, sensitive, standard) to each flow based on data classification, blast radius, and regulatory requirements. Critical flows get the strictest controls.
+3. **Implement Identity Verification Per Flow**: Require cryptographic identity proof for every request — no request is trusted based on network location alone. Use SPIFFE/SPIRE or equivalent workload identity framework.
+4. **Enable mTLS for Service-to-Service**: Configure mutual TLS for all internal service communication. Automate certificate rotation with short-lived certificates (hours, not months). Define CA hierarchy.
+5. **Configure Micro-Segmentation Policies**: Replace flat network trust with fine-grained allow-list policies. Each service can only communicate with explicitly authorized peers on explicitly authorized ports.
+6. **Add Device Posture Checks**: For user-facing access, verify device health (OS patch level, disk encryption, endpoint protection) before granting access. Degrade gracefully for non-compliant devices.
+7. **Remove Implicit Trust**: Eliminate VPN-equals-trust model. Being on the corporate network grants zero additional privileges. All access requires explicit authentication and authorization regardless of network origin.
+8. **Set Up Continuous Verification**: Implement session re-validation at regular intervals. Monitor for anomalous behavior patterns and trigger step-up authentication or session termination on drift detection.
+9. **Document Access Policies**: Produce a comprehensive policy matrix mapping identities to resources with conditions. Store policies as code for version control, audit, and automated enforcement.
+10. **Validate with Penetration Testing**: Design adversarial tests that simulate lateral movement, credential theft, and privilege escalation to verify zero-trust controls prevent blast radius expansion.
+</process>

package/.mindforge/config.json

@@ -1,11 +1,11 @@
 {
-  "version": "11.3.0",
+  "version": "11.4.0",
   "environment": "development",
   "governance": {
     "drift_threshold": 0.75,
     "critical_drift_threshold": 0.5,
     "res_threshold": 0.8,
-    "active_did": "did:mindforge:0342751c-bbaf-4528-b4ae-47feacef7510"
+    "active_did": "did:mindforge:39723c91-8532-400f-855f-720ec0a5387c"
   },
   "revops": {
     "market_registry": {

package/.mindforge/governance/GOVERNANCE-CONFIG.md

@@ -0,0 +1,17 @@
+# MindForge Governance Configuration
+
+## Tier policy
+- Tier 1: low-risk documentation or isolated code cleanup
+- Tier 2: broader product or operational changes
+- Tier 3: security, privacy, auth, secrets, payments, compliance, or emergency
+
+## Enforcement rules
+- Tier 3 signals have higher priority than file-count heuristics
+- Compliance gates are blocking
+- Integration failures are non-fatal unless they prevent a required approval or
+  compliance decision from being observed
+
+## Record locations
+- Approval files: `.planning/approvals/`
+- Audit archive: `.planning/audit-archive/`
+- Milestones: `.planning/milestones/`

package/.mindforge/governance/approval-workflow.md

@@ -0,0 +1,37 @@
+# MindForge Governance — Approval Workflow
+
+## Purpose
+Define the human approval process for Tier 2 peer review, Tier 3
+ security/compliance review, and emergency override handling.
+
+## Approval sources
+Approvals are represented as files in `.planning/approvals/`. Commands must list
+ only `status: pending` approval requests by default.
+
+## Identity model
+Current approver identity is derived from `git config user.email` or `$USER`.
+This is convenient but spoofable. For higher-assurance environments, integrate
+ the approval flow with your IdP or SCM identity provider.
+
+## Standard workflow
+1. Classifier determines tier
+2. Create approval file with reason, scope, diff summary, and expiry time
+3. Notify configured approvers
+4. Record approval or rejection
+5. On rejection, create a fix task that carries the rejection reason forward
+6. Re-request approval only after the rejection reason has been addressed
+
+## Expiry and SLA handling
+Expiry processing is session-dependent. If no MindForge session is active, an
+ expired approval will be detected the next time the approval command runs.
+
+Use config-driven values from `INTEGRATIONS-CONFIG.md`:
+- `TIER2_APPROVERS`
+- `TIER3_APPROVERS`
+- `EMERGENCY_APPROVERS`
+- SLA and expiry hour settings
+
+## Emergency override
+Emergency approval requires the `--emergency` flag and an approver identity that
+ appears in `EMERGENCY_APPROVERS`. Log the approver identity and rationale in
+ AUDIT. Emergency override bypass is never implicit.

package/.mindforge/governance/change-classifier.md

@@ -0,0 +1,63 @@
+# MindForge Governance — Change Classifier
+
+## Purpose
+Assign each change a governance tier before execution and again before release.
+Tier 3 signals always override lower-risk heuristics.
+
+## Trigger points
+- Before each plan executes
+- Before PR or merge request creation
+- Before emergency override requests are processed
+
+## Tier model
+
+| Tier | Meaning | Approval requirement |
+|---|---|---|
+| 1 | Low-risk documentation or isolated refactor | none |
+| 2 | Broad change, cross-cutting impact, or moderate operational risk | peer approval |
+| 3 | Security, privacy, auth, payment, secrets, or compliance-sensitive | security/compliance approval |
+
+## Step 1 — Base heuristics
+- More than 10 files or more than 300 lines changed defaults to Tier 2
+- Infra, deployment, or schema changes default to at least Tier 2
+- File count is only a signal; it never downgrades a Tier 3 match
+
+## Step 2 — Apply Tier 3 rules first
+Tier 3 uses three independent signals. Any one match makes the change Tier 3.
+
+### Signal A — File path patterns
+Security-critical directories and files:
+`auth/`, `security/`, `payment/`, `billing/`, `privacy/`, `crypto/`, `secrets/`
+
+Security-critical names:
+`login.ts`, `logout.ts`, `token.ts`, `password.ts`, `credentials.ts`,
+`session.ts`, `oauth.ts`, `jwt.ts`, `hash.ts`, `encrypt.ts`, `stripe.ts`,
+`payment.ts`, `billing.ts`, `pii.ts`, `consent.ts`
+
+### Signal B — Code content patterns
+Scan the actual diff content, not only filenames, for patterns such as:
+`bcrypt`, `argon2`, `jwt.sign`, `jwt.verify`, `jose.sign`, `jose.verify`,
+`stripe.`, `paypal.`, `createCipheriv`, `createDecipheriv`, `crypto.subtle`,
+`hashPassword`, `verifyPassword`, `encrypt(`, `decrypt(`, `role.*permission`,
+`hasPermission`, `SET ROLE`, `GRANT`
+
+This protects against security-critical code being added to innocuous filenames
+ like `src/utils/helper.ts`.
+
+### Signal C — AUDIT history patterns
+If the current phase has a recent HIGH or CRITICAL `security_finding`, the next
+ change in that phase is elevated to Tier 3 automatically.
+
+## Classification audit entry
+Record why the tier was selected:
+
+```json
+{
+  "event": "change_classified",
+  "tier": 3,
+  "classification_reason": "code pattern: jwt.sign found in src/utils/helper.ts",
+  "signals_checked": ["file_path", "code_content", "audit_history"],
+  "signal_triggered": "code_content",
+  "pattern_matched": "jwt.sign"
+}
+```

package/.mindforge/governance/compliance-gates.md

@@ -0,0 +1,31 @@
+# MindForge Governance — Compliance Gates
+
+## Purpose
+Apply non-bypassable release gates for secrets, approvals, and privacy controls.
+
+## Gate 1 — Required verification
+The plan's verify step and the project test suite must pass.
+
+## Gate 2 — Required approvals
+Tier 2 and Tier 3 changes must have approved, non-expired approval records.
+
+## Gate 3 — Secret detection
+No real secrets may enter the diff, audit log, or published docs.
+Override is not permitted.
+
+For tests that exercise secret detection, use clearly fake patterns that do not
+ match production secret regexes, for example `TEST_ONLY_FAKE_KEY_abc123`.
+
+## Gate 4 — GDPR/PII compliance check
+This gate runs independently of skill loading.
+
+Trigger if the diff adds fields or columns resembling:
+`email`, `phone`, `mobile`, `address`, `postcode`, `zip`, `ssn`, `dob`,
+`birth_date`, `first_name`, `last_name`, `national_id`, `passport`,
+`credit_card`, `bank_account`, `iban`, `bic`
+
+If triggered, verify `.planning/ARCHITECTURE.md` documents retention policy for
+ the relevant data. If retention is missing:
+- block completion
+- write `compliance_gate_failed` to AUDIT
+- require Tier 3 compliance approval for override

package/.mindforge/governance/policies/sovereign-default.json

@@ -0,0 +1,16 @@
+{
+  "id": "SOV-001",
+  "name": "Sovereign Default Policy",
+  "description": "Enables Sovereign Intelligence v8.1.1 features by default.",
+  "effect": "PERMIT",
+  "max_impact": 100,
+  "conditions": {
+    "did": "agent:*",
+    "min_tier": 1
+  },
+  "sovereign_config": {
+    "pqas": "ENABLED",
+    "proactive_homing": "ENABLED",
+    "biometric_threshold": 95
+  }
+}

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.