mindforge-cc 8.1.1 → 8.2.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/.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/mirrors/mirror-sre-776a1cf9/.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/mirrors/mirror-sre-776a1cf9/.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/mirrors/mirror-sre-776a1cf9/.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/mirrors/mirror-sre-776a1cf9/.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/mirrors/mirror-sre-776a1cf9/.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/mirrors/mirror-sre-776a1cf9/.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/mirrors/mirror-sre-776a1cf9/.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.