mindforge-cc 1.0.0

package/.planning/decisions/ADR-019-self-update-scope-preservation.md

@@ -0,0 +1,14 @@
+# ADR-019: Self-update preserves the original installation scope
+
+**Status:** Accepted | **Date:** v1.0.0 | **Day:** 7
+
+## Context
+`/mindforge:update --apply` must update the correct installation.
+
+## Decision
+Detect original scope from filesystem (local before global per priority).
+Apply update using the detected scope. Per ADR-019.
+
+## Rationale
+Principle of least surprise. A local install user should get a local update.
+Unexpected global install is confusing and may affect other projects.

package/.planning/decisions/ADR-020-v1.0.0-stable-interface-contract.md

@@ -0,0 +1,23 @@
+# ADR-020: v1.0.0 stable interface contract
+
+**Status:** Accepted | **Date:** v1.0.0 | **Day:** 7
+
+## Context
+MindForge reaches v1.0.0. "Stable" must be precisely defined.
+
+## Decision
+Stable public interfaces (additions require MINOR, removals/changes require MAJOR):
+- All 36 command names and their flag interfaces
+- HANDOFF.json schema fields
+- AUDIT.jsonl event types and required fields
+- All 10 core skill name values
+- MINDFORGE.md setting keys
+- @mindforge/sdk exported types and functions
+- plugin.json manifest format
+
+Governance primitives are permanently fixed and cannot become configurable
+in any future version without a MAJOR bump and explicit RFC process.
+
+## Consequences
+Plugin authors and SDK consumers can build on v1.0.0 with confidence.
+The MindForge team is committed to backwards compatibility in 1.x.x releases.

package/.planning/jira-sync.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": "1.0.0",
+  "last_sync": null,
+  "project_key": null,
+  "phase_mappings": {},
+  "transition_cache": {},
+  "security_bugs": [],
+  "_warning": "Do not store credentials in this file."
+}

package/.planning/milestones/.gitkeep

@@ -0,0 +1 @@
+

package/.planning/phases/day1/REVIEW-DAY1.md

@@ -0,0 +1,50 @@
+# Day 1 Review — MindForge Foundation
+
+## Summary
+Overall structure matches the Day 1 specification and is consistent across Claude and Antigravity.
+However, several blocking and major issues remain around ambiguity, safety, and hardening.
+
+## BLOCKING findings
+1. **CLAUDE.md missing explicit missing-file handling and plan validation**
+   - Impact: Agents can proceed with undefined state or malformed plans.
+   - Evidence: CLAUDE.md lacks required missing-file handling and plan validation steps.
+   - Recommendation: Add explicit missing-file handling, plan validation, and quality gate enforcement (see HARDEN 2).
+
+2. **HANDOFF.json lacks anti-secret warning and expanded schema fields**
+   - Impact: Risk of secrets being recorded in tracked state files.
+   - Evidence: HANDOFF.json template has no warning and minimal fields.
+   - Recommendation: Add `_warning`, `session_summary`, `recent_files`, `recent_commits` (see HARDEN 6).
+
+3. **Installer lacks node version guard, CLAUDE.md backup, and install verification**
+   - Impact: Silent failures and risk of overwriting user CLAUDE.md.
+   - Evidence: bin/install.js has no version check or backup of non-MindForge CLAUDE.md.
+   - Recommendation: Implement version guard, safe copy, and post-install verification (see HARDEN 5).
+
+## MAJOR findings
+1. **Slash commands missing explicit edge-case handling**
+   - Impact: execute-phase does not define behaviour for malformed XML or missing test suite.
+   - Evidence: execute-phase.md does not address malformed XML or missing test runner.
+   - Recommendation: Add explicit failure handling in execute-phase.md.
+
+2. **State updates inconsistent**
+   - Impact: ship command does not update STATE.md at end.
+   - Evidence: ship.md does not specify state update.
+   - Recommendation: Add explicit STATE.md update to ship.md.
+
+3. **.gitignore missing key/cert patterns**
+   - Impact: risk of accidental commit of private keys.
+   - Evidence: no *.key or *.pem patterns.
+   - Recommendation: add *.key and *.pem to .gitignore.
+
+## MINOR findings
+1. **CLAUDE.md lacks explicit guidance for corrupt HANDOFF.json**
+   - Impact: ambiguous recovery path on parse errors.
+   - Recommendation: include guidance (HARDEN 2 section).
+
+2. **Help command lacks pre-check**
+   - Impact: minimal, but review spec expects pre-checks for all commands.
+   - Recommendation: Add a lightweight pre-check (e.g., read STATE.md if present).
+
+## Decision required
+- HANDOFF.json tracking: Should it be tracked or gitignored?
+  Recommendation: Track in git with explicit anti-secret warning and ADR (HARDEN 7).

package/.planning/phases/day1/SECURITY-REVIEW-DAY1.md

@@ -0,0 +1,15 @@
+# Day 1 Security Review — MindForge Foundation
+
+## Findings
+
+### MEDIUM — HANDOFF.json could capture secrets
+- Risk: Session state files are tracked in git; secrets could be recorded.
+- Recommendation: Add `_warning` field and explicit note in STATE.md. Add ADR documenting tracking decision.
+
+### MEDIUM — .gitignore missing key/cert patterns
+- Risk: Private keys or certs can be committed accidentally.
+- Recommendation: Add `*.key` and `*.pem` to .gitignore.
+
+### LOW — Installer overwrites CLAUDE.md without backup
+- Risk: User's existing agent config could be lost.
+- Recommendation: Add CLAUDE.md backup when overwriting non-MindForge files.

package/.planning/phases/day2/REVIEW-DAY2.md

@@ -0,0 +1,521 @@
+## Finding 1 — BLOCKING: HANDOFF.json schema mismatch across docs
+
+**File:** .mindforge/engine/compaction-protocol.md
+**Category:** Consistency
+**Severity:** BLOCKING
+
+**Issue:**
+Compaction protocol writes a HANDOFF.json schema with fields like `plan_step`, `in_progress`, `recent_commits`, `recent_files`, and `agent_notes`, but the init-project template and base HANDOFF.json do not include these fields. This creates conflicting expectations between commands and engine specs.
+
+**Impact:**
+Session restart logic can break or silently drop fields. Different agents will write incompatible HANDOFF.json files.
+
+**Recommendation:**
+Update the canonical HANDOFF.json template and init-project command to include all fields required by compaction-protocol.md.
+
+---
+## Finding 2 — BLOCKING: AUDIT schema missing events used by execute-phase
+
+**File:** .mindforge/audit/AUDIT-SCHEMA.md
+**Category:** Audit
+**Severity:** BLOCKING
+
+**Issue:**
+The execute-phase command writes `phase_execution_started` and `phase_execution_completed`, but these event types are not defined in AUDIT-SCHEMA.md.
+
+**Impact:**
+Audit log becomes inconsistent and unverifiable. Consumers parsing AUDIT.jsonl cannot validate these events.
+
+**Recommendation:**
+Add explicit schema entries for `phase_execution_started` and `phase_execution_completed` (with required fields).
+
+---
+## Finding 3 — MAJOR: Dependency report lacks explicit wave assignments
+
+**File:** .mindforge/engine/dependency-parser.md
+**Category:** Wave Engine
+**Severity:** MAJOR
+
+**Issue:**
+DEPENDENCY-GRAPH template does not include wave assignments per plan. It only lists tasks and a generic "Wave 1 → Wave 2" note.
+
+**Impact:**
+execute-phase cannot consume the dependency report without re-running wave grouping. Operators cannot verify the planned wave layout.
+
+**Recommendation:**
+Add a "Wave" column to the task table and/or add a dedicated "Wave assignments" section listing each wave's plan IDs.
+
+---
+## Finding 4 — MAJOR: Wave executor lacks subagent invocation guidance
+
+**File:** .mindforge/engine/wave-executor.md
+**Category:** Wave Engine
+**Severity:** MAJOR
+
+**Issue:**
+The spec says "spawn a subagent" but does not describe how to do this in Claude Code vs Antigravity. This is runtime-specific and currently ambiguous.
+
+**Impact:**
+Different agents will interpret this differently, causing inconsistent execution across runtimes.
+
+**Recommendation:**
+Add a short runtime-agnostic protocol for subagent invocation or a dedicated section with Claude Code vs Antigravity guidance.
+
+---
+## Finding 5 — MAJOR: Wave executor missing timeout / hang handling
+
+**File:** .mindforge/engine/wave-executor.md
+**Category:** Wave Engine
+**Severity:** MAJOR
+
+**Issue:**
+No guidance on what to do if a subagent never returns or a SUMMARY file is never written.
+
+**Impact:**
+Wave execution can hang indefinitely.
+
+**Recommendation:**
+Add a timeout rule (e.g., if no SUMMARY after N minutes, mark task blocked and stop wave).
+
+---
+## Finding 6 — MAJOR: Wave executor assumes tests exist
+
+**File:** .mindforge/engine/wave-executor.md
+**Category:** Wave Engine
+**Severity:** MAJOR
+
+**Issue:**
+It mandates full test suite after each wave but does not define behavior if no test suite exists yet.
+
+**Impact:**
+Early projects may block with no clear next action.
+
+**Recommendation:**
+Define a fallback: if no test command exists, stop and instruct user to add tests or define the test command.
+
+---
+## Finding 7 — MAJOR: WAVE-REPORT template lacks failure representation
+
+**File:** .mindforge/engine/wave-executor.md
+**Category:** Wave Engine
+**Severity:** MAJOR
+
+**Issue:**
+WAVE-REPORT template only shows successful rows. No explicit failure row format or error capture.
+
+**Impact:**
+Failed waves are hard to audit; execution history becomes misleading.
+
+**Recommendation:**
+Add explicit failure row format with error output and status icon.
+
+---
+## Finding 8 — MAJOR: Context injector does not define completion signal
+
+**File:** .mindforge/engine/context-injector.md
+**Category:** Wave Engine
+**Severity:** MAJOR
+
+**Issue:**
+The spec says "report completion status" but does not define the mechanism (file path, message format).
+
+**Impact:**
+Orchestrator cannot reliably detect task completion across runtimes.
+
+**Recommendation:**
+Define completion signal as the presence of SUMMARY-[N]-[M].md plus explicit status line inside it.
+
+---
+## Finding 9 — MAJOR: Context injector lacks placeholder detection
+
+**File:** .mindforge/engine/context-injector.md
+**Category:** Security
+**Severity:** MAJOR
+
+**Issue:**
+SECURITY.md is injected but may still contain placeholder text. No warning or validation exists.
+
+**Impact:**
+Subagents assume security requirements are defined when they are not.
+
+**Recommendation:**
+Add a check: if SECURITY.md contains placeholders, warn the user to fill it in before sensitive work.
+
+---
+## Finding 10 — MAJOR: Context injector path traversal risk in ADR references
+
+**File:** .mindforge/engine/context-injector.md
+**Category:** Security
+**Severity:** MAJOR
+
+**Issue:**
+Plans can reference ADR paths; no validation ensures referenced files are within repo.
+
+**Impact:**
+Potential path traversal or unintended file disclosure.
+
+**Recommendation:**
+Validate that all referenced paths are under project root before inclusion.
+
+---
+## Finding 11 — MAJOR: Verification pipeline Stage 1 failure has no remediation path
+
+**File:** .mindforge/engine/verification-pipeline.md
+**Category:** Wave Engine
+**Severity:** MAJOR
+
+**Issue:**
+Stage 1 says "stop" but does not describe whether to create fix plans or how to proceed.
+
+**Impact:**
+Users have no defined remediation workflow.
+
+**Recommendation:**
+Add explicit instruction to create fix plans when Stage 1 fails.
+
+---
+## Finding 12 — MAJOR: AUDIT schema missing additional event types
+
+**File:** .mindforge/audit/AUDIT-SCHEMA.md
+**Category:** Audit
+**Severity:** MAJOR
+
+**Issue:**
+Missing event definitions for: `quick_task_completed`, `debug_completed`, `uat_started`, `uat_completed`, `ship_started`, `ship_completed`, `session_started`.
+
+**Impact:**
+Audit log coverage is incomplete for key lifecycle actions.
+
+**Recommendation:**
+Add schema entries for all missing events.
+
+---
+## Finding 13 — MAJOR: AUDIT schema lacks corruption recovery guidance
+
+**File:** .mindforge/audit/AUDIT-SCHEMA.md
+**Category:** Audit
+**Severity:** MAJOR
+
+**Issue:**
+No guidance for handling corrupted AUDIT.jsonl or long-term file growth.
+
+**Impact:**
+Audit system can become unusable over time without a recovery path.
+
+**Recommendation:**
+Add brief guidance: restore from git history, and archive to AUDIT-archive-YYYY.jsonl when size exceeds threshold.
+
+---
+## Finding 14 — MAJOR: Compaction protocol missing mid-wave handling
+
+**File:** .mindforge/engine/compaction-protocol.md
+**Category:** Compaction
+**Severity:** MAJOR
+
+**Issue:**
+No guidance for compaction when a subagent is still running in the current wave.
+
+**Impact:**
+Compaction could interrupt or duplicate work.
+
+**Recommendation:**
+Specify: wait for running subagents to complete before compacting.
+
+---
+## Finding 15 — MAJOR: Compaction protocol WIP commits do not address hooks
+
+**File:** .mindforge/engine/compaction-protocol.md
+**Category:** Compaction
+**Severity:** MAJOR
+
+**Issue:**
+WIP commit step does not address pre-commit hooks.
+
+**Impact:**
+Compaction can fail if hooks require lint/tests.
+
+**Recommendation:**
+Use `git commit --no-verify` for compaction WIP checkpoints and document it in STATE.md.
+
+---
+## Finding 16 — MAJOR: Compaction protocol lacks HANDOFF staleness handling
+
+**File:** .mindforge/engine/compaction-protocol.md
+**Category:** Compaction
+**Severity:** MAJOR
+
+**Issue:**
+No staleness check for old HANDOFF.json.
+
+**Impact:**
+Agents may continue from outdated state without warning.
+
+**Recommendation:**
+Warn if `updated_at` is older than 48 hours and confirm continuation.
+
+---
+## Finding 17 — MAJOR: Compaction protocol lacks concurrent session warning
+
+**File:** .mindforge/engine/compaction-protocol.md
+**Category:** Compaction
+**Severity:** MAJOR
+
+**Issue:**
+No mention of multiple agents using the same HANDOFF.json concurrently.
+
+**Impact:**
+Race conditions and state corruption.
+
+**Recommendation:**
+Add a warning that concurrent sessions are unsupported and require manual coordination.
+
+---
+## Finding 18 — MAJOR: /mindforge:next prioritizes HANDOFF.json too late
+
+**File:** .claude/commands/mindforge/next.md
+**Category:** Commands
+**Severity:** MAJOR
+
+**Issue:**
+HANDOFF.json handling is described after the decision tree, not as a priority path.
+
+**Impact:**
+The system may ignore an interrupted session and start a new flow.
+
+**Recommendation:**
+Move HANDOFF.json handling to the top: if it exists and is recent, prompt user before normal state detection.
+
+---
+## Finding 19 — MAJOR: /mindforge:quick lacks numbering collision prevention
+
+**File:** .claude/commands/mindforge/quick.md
+**Category:** Commands
+**Severity:** MAJOR
+
+**Issue:**
+No rule for choosing next quick task number; concurrent runs may both use 001.
+
+**Impact:**
+Directory collisions and overwritten plans.
+
+**Recommendation:**
+Define numbering: scan `.planning/quick/`, take max + 1, and require `--force` if collision.
+
+---
+## Finding 20 — MAJOR: /mindforge:quick missing security auto-trigger
+
+**File:** .claude/commands/mindforge/quick.md
+**Category:** Security
+**Severity:** MAJOR
+
+**Issue:**
+Quick tasks do not auto-trigger the security-review skill for security-sensitive keywords.
+
+**Impact:**
+Security-sensitive quick fixes can bypass security review.
+
+**Recommendation:**
+Add rule: if task description contains security keywords, load security-review skill regardless of flags.
+
+---
+## Finding 21 — MAJOR: /mindforge:debug lacks full test-suite verification
+
+**File:** .claude/commands/mindforge/debug.md
+**Category:** Commands
+**Severity:** MAJOR
+
+**Issue:**
+Debug protocol does not require running full test suite after fix.
+
+**Impact:**
+Fix could introduce regressions unnoticed.
+
+**Recommendation:**
+Add step to run full test suite after fix, before marking done.
+
+---
+## Finding 22 — MINOR: /mindforge:status progress counts failed tasks
+
+**File:** .claude/commands/mindforge/status.md
+**Category:** Commands
+**Severity:** MINOR
+
+**Issue:**
+Progress calculation uses SUMMARY count without checking `Status: Completed ✅`.
+
+**Impact:**
+Failed tasks could inflate progress.
+
+**Recommendation:**
+Count only SUMMARY files with explicit completed status.
+
+---
+## Finding 23 — MINOR: /mindforge:status does not address empty AUDIT.jsonl
+
+**File:** .claude/commands/mindforge/status.md
+**Category:** Commands
+**Severity:** MINOR
+
+**Issue:**
+No guidance for empty audit log on fresh projects.
+
+**Impact:**
+Potential confusing output.
+
+**Recommendation:**
+Add "No activity logged yet" when AUDIT.jsonl is empty.
+
+---
+## Finding 24 — MINOR: /mindforge:status requirements coverage assumes VERIFICATION.md exists
+
+**File:** .claude/commands/mindforge/status.md
+**Category:** Commands
+**Severity:** MINOR
+
+**Issue:**
+No fallback if VERIFICATION.md does not exist yet.
+
+**Impact:**
+Incomplete status output.
+
+**Recommendation:**
+Add "In progress" state when verification is missing.
+
+---
+## Finding 25 — MINOR: /mindforge:quick does not mention STATE.md update policy
+
+**File:** .claude/commands/mindforge/quick.md
+**Category:** Commands
+**Severity:** MINOR
+
+**Issue:**
+No guidance on whether quick tasks update STATE.md.
+
+**Impact:**
+State consistency varies by operator.
+
+**Recommendation:**
+Specify: quick tasks do not change phase status; note quick task in STATE.md if no active phase.
+
+---
+## Finding 26 — MINOR: Dependency parser does not address duplicate task names
+
+**File:** .mindforge/engine/dependency-parser.md
+**Category:** Wave Engine
+**Severity:** MINOR
+
+**Issue:**
+No rule for duplicate `<n>` values across different plan IDs.
+
+**Impact:**
+Potential confusion in summaries and audit entries.
+
+**Recommendation:**
+Require uniqueness or prefix summaries with plan ID.
+
+---
+## Finding 27 — MINOR: Verification pipeline grep false negatives
+
+**File:** .mindforge/engine/verification-pipeline.md
+**Category:** Wave Engine
+**Severity:** MINOR
+
+**Issue:**
+Stage 2 relies on exact text matches; does not define fallback for false negatives.
+
+**Impact:**
+Requirements may be marked ⚠️ or ❌ incorrectly.
+
+**Recommendation:**
+Add a manual confirmation step when grep finds nothing.
+
+---
+## Finding 28 — MINOR: Audit schema lacks note about sensitive rationale text
+
+**File:** .mindforge/audit/AUDIT-SCHEMA.md
+**Category:** Security
+**Severity:** MINOR
+
+**Issue:**
+`decision_recorded.rationale` could contain secrets if a user pastes credentials.
+
+**Impact:**
+Sensitive data leakage into AUDIT.jsonl.
+
+**Recommendation:**
+Add warning to schema: never include secrets in rationale fields.
+
+---
+## Finding 29 — SUGGESTION: Add missing tests for edge cases
+
+**File:** tests/wave-engine.test.js
+**Category:** Test Suite
+**Severity:** SUGGESTION
+
+**Issue:**
+Wave engine tests lack cases for empty graph, self-dependency, missing dependency, and 3+ plan conflicts.
+
+**Impact:**
+Edge case regressions may go unnoticed.
+
+**Recommendation:**
+Add the missing tests listed in DAY2-REVIEW.md.
+
+---
+## Finding 30 — SUGGESTION: Add audit tests for UUID format and mixed JSONL
+
+**File:** tests/audit.test.js
+**Category:** Test Suite
+**Severity:** SUGGESTION
+
+**Issue:**
+Audit tests do not explicitly test invalid UUID formats or mixed valid/invalid lines.
+
+**Impact:**
+Parser may accept malformed entries.
+
+**Recommendation:**
+Add explicit tests for invalid UUID format and mixed JSONL lines.
+
+---
+## Finding 31 — SUGGESTION: Add compaction tests for recent_commits and in_progress
+
+**File:** tests/compaction.test.js
+**Category:** Test Suite
+**Severity:** SUGGESTION
+
+**Issue:**
+Compaction tests do not verify `recent_commits` or `in_progress` fields exist.
+
+**Impact:**
+HANDOFF schema could drift without detection.
+
+**Recommendation:**
+Add tests for `recent_commits` and `in_progress` fields.
+
+---
+## Day 2 Review Summary
+
+| Category      | BLOCKING | MAJOR | MINOR | SUGGESTION |
+|---------------|----------|-------|-------|------------|
+| Wave Engine   | 0        | 6     | 2     | 1          |
+| Audit System  | 1        | 2     | 1     | 1          |
+| Compaction    | 0        | 4     | 0     | 1          |
+| Commands      | 0        | 5     | 4     | 0          |
+| Test Suite    | 0        | 0     | 0     | 3          |
+| Consistency   | 1        | 0     | 0     | 0          |
+| Security      | 0        | 2     | 1     | 0          |
+| **TOTAL**     | 2        | 19    | 8     | 6          |
+
+## Verdict
+[ ] ✅ APPROVED — Proceed to DAY2-HARDEN.md
+[ ] ⚠️  APPROVED WITH CONDITIONS — Fix [N] major findings first
+[x] ❌ NOT APPROVED — 2 blocking findings. Fix and re-review.
+
+## Estimated fix time
+3–5 hours
+## Review Status
+**Approved after fixes — 2026-03-20**
+
+All BLOCKING and MAJOR findings below have been addressed in subsequent hardening commits.
+This document preserves the original review record.