open-xmen 0.1.0

package/.cerebro/scripts/validate-upgrade-metadata.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Validate Cerebro upgrade manifest and upgrade state metadata."""
+
+import json
+import re
+from pathlib import Path
+
+
+VALID_OWNERSHIPS = {"template", "merge", "user"}
+SHA_RE = re.compile(r"^[0-9a-f]{40}$")
+
+
+def main() -> int:
+    errors = []
+    errors.extend(validate_json_file(Path(".cerebro/schemas/upgrade-manifest.schema.json")))
+    errors.extend(validate_json_file(Path(".cerebro/schemas/upgrade-state.schema.json")))
+    errors.extend(validate_manifest())
+    errors.extend(validate_state())
+
+    if errors:
+        for error in errors:
+            print(error)
+        return 1
+
+    return 0
+
+
+def validate_json_file(path: Path) -> list[str]:
+    if not path.exists():
+        return [f"{path} missing"]
+    try:
+        json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return [f"{path} invalid JSON: {exc}"]
+    print(f"{path.name} valid")
+    return []
+
+
+def validate_manifest() -> list[str]:
+    manifest_path = Path(".cerebro/upgrade-manifest.json")
+    if not manifest_path.exists():
+        print("no manifest present (informational - run /cerebro-upgrade to initialize)")
+        return []
+
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return [f"upgrade-manifest.json invalid JSON: {exc}"]
+    errors = []
+    entries = manifest.get("entries", [])
+    if not isinstance(entries, list) or not entries:
+        errors.append("entries must be a non-empty array")
+        return errors
+
+    for index, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            errors.append(f"entry {index}: must be an object")
+            continue
+        if "path" not in entry:
+            errors.append(f"entry {index}: missing 'path'")
+        if "ownership" not in entry:
+            errors.append(f"entry {index}: missing 'ownership'")
+        elif entry["ownership"] not in VALID_OWNERSHIPS:
+            errors.append(
+                f"entry {index}: invalid ownership '{entry['ownership']}' "
+                "(must be template, merge, or user)"
+            )
+
+    if not errors:
+        print(f"manifest entries ok ({len(entries)} entries)")
+    return errors
+
+
+def validate_state() -> list[str]:
+    state_path = Path(".cerebro/upgrade-state.json")
+    if not state_path.exists():
+        print("no upgrade-state.json present (informational - will be written after first /cerebro-upgrade)")
+        return []
+
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return [f"upgrade-state.json invalid JSON: {exc}"]
+    errors = []
+    required = {"version", "applied_ref", "applied_sha", "applied_at", "hashes"}
+    missing = sorted(required - set(state))
+    if missing:
+        errors.append(f"upgrade-state.json missing fields: {missing}")
+    if state.get("version") != 1:
+        errors.append(f"unexpected version: {state.get('version')}")
+
+    sha = state.get("applied_sha", "")
+    if not SHA_RE.match(sha):
+        errors.append(f"applied_sha is not a 40-char hex: {sha!r}")
+    if not isinstance(state.get("hashes"), dict):
+        errors.append("hashes must be an object")
+
+    if not errors:
+        print(f"upgrade-state.json valid (ref={state['applied_ref']}, sha={sha[:8]}...)")
+    return errors
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.cerebro/scripts/write-upgrade-state.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Atomically write .cerebro/upgrade-state.json from current owned file hashes."""
+
+import argparse
+import fnmatch
+import hashlib
+import json
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+OWNED_FOR_BASELINE = {"template", "merge"}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--ref", required=True, dest="applied_ref")
+    parser.add_argument("--sha", required=True, dest="applied_sha")
+    parser.add_argument("--manifest", default=".cerebro/upgrade-manifest.json")
+    parser.add_argument("--output", default=".cerebro/upgrade-state.json")
+    args = parser.parse_args()
+
+    manifest_path = Path(args.manifest)
+    if not manifest_path.exists():
+        print(f"manifest not found: {manifest_path}")
+        return 1
+
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    hashes = collect_hashes(manifest)
+    state = {
+        "version": 1,
+        "applied_ref": args.applied_ref,
+        "applied_sha": args.applied_sha,
+        "applied_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "hashes": hashes,
+    }
+
+    output = Path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        "w",
+        encoding="utf-8",
+        dir=output.parent,
+        prefix=output.stem + ".",
+        suffix=".tmp",
+        delete=False,
+    ) as handle:
+        json.dump(state, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+        tmp_path = Path(handle.name)
+    tmp_path.replace(output)
+    print(f"wrote {output} with {len(hashes)} file hash(es)")
+    return 0
+
+
+def collect_hashes(manifest: dict) -> dict[str, str]:
+    paths = set()
+    for entry in manifest.get("entries", []):
+        if entry.get("ownership") not in OWNED_FOR_BASELINE:
+            continue
+        pattern = entry.get("path")
+        if not pattern:
+            continue
+        paths.update(expand_pattern(pattern))
+
+    return {path: sha256(Path(path)) for path in sorted(paths) if Path(path).is_file()}
+
+
+def expand_pattern(pattern: str) -> set[str]:
+    if not _has_glob(pattern):
+        return {pattern} if Path(pattern).is_file() else set()
+    return {
+        str(path)
+        for path in Path(".").rglob("*")
+        if path.is_file() and fnmatch.fnmatch(str(path).removeprefix("./"), pattern)
+    }
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _has_glob(pattern: str) -> bool:
+    return any(char in pattern for char in "*?[")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.cerebro/templates/customer-vision.md

@@ -0,0 +1,58 @@
+# [Product Name] — Customer Vision & Acceptance
+
+**Voice:** Legion (Customer / Product-Owner proxy)
+**Request:** [The user's original request, verbatim or lightly cleaned.]
+
+## The Customer's Premise
+
+[2–3 sentences in the customer's voice: what I'm trying to do and why I care. The mindset of the person this is for.]
+
+## Personas
+
+For each distinct user this product must satisfy:
+
+### [Persona name]
+
+- **Context:** [Who they are, when/where/why they reach for this.]
+- **What delights them:** [What makes them love it.]
+- **What makes them bounce:** [Friction or absence that makes them quit.]
+- **Will not tolerate:** [Hard deal-breakers.]
+
+## Must-Haves (non-negotiable)
+
+- [Capability or quality the product cannot ship without.]
+
+## Deal-Breakers
+
+- [Things that, if present or missing, mean I reject the product outright.]
+
+## Quality Bar — "Great, Not Generic"
+
+What separates a product I'd recommend from a forgettable demo:
+
+- **Experience:** [What the core flow must feel like.]
+- **Polish:** [The finish that signals craft.]
+- **Completeness:** [States and edges a real user hits that must be handled.]
+
+## Competitive Expectations
+
+Grounded in real products in this space (from research):
+
+- **[Product / pattern]** — [What it does well that sets my expectation] — [source]
+
+## Success In One Sentence
+
+> [The customer's own definition of "this works and I'd use it."]
+
+---
+
+## Acceptance Record (filled in Mode 2, end of build)
+
+**Verdict:** ACCEPT | REJECT | (pending)
+**Would I use this:** [one honest sentence]
+
+**Gaps found:**
+- [As a {persona}: what broke the experience — what good requires — where it fell short, or None]
+
+**Genuinely good:**
+- [Earned praise, or None yet]

package/.cerebro/templates/plan.md

@@ -0,0 +1,35 @@
+# [Plan Name]
+
+**Objective:** [One sentence describing the user-visible change.]
+**Risk Level:** LOW | MEDIUM | HIGH
+
+## Assumptions and Decisions
+
+- [Decision or assumption that affects implementation.]
+
+## Approval Gates
+
+- [ ] None
+
+Use explicit gates for destructive, irreversible, privileged, external mutating, production, data, auth, billing, dependency-upgrade, or git-history actions.
+
+## Acceptance Criteria
+
+- [ ] [Concrete pass/fail criterion.]
+- [ ] [Concrete pass/fail criterion.]
+
+## Tasks
+
+### Task 1: [Name]
+
+**Owner:** Wolverine | Storm | Cyclops | Forge consultation
+**Files:** `[exact/path.ext]` (modify/create) or `None`
+**What:** [Specific implementation or verification action.]
+**TDD:** [Failing test to write first, or "Not applicable: [reason]".]
+**Verify:** `[exact command or manual check]`
+**Risk:** LOW | MEDIUM | HIGH
+**Approval Gate:** None | [Gate name from Approval Gates]
+
+## Rollback / Recovery
+
+- [How to undo or recover if execution fails. Use "Not applicable" only for low-risk docs/config-only work.]

package/.cerebro/templates/product-brief.md

@@ -0,0 +1,110 @@
+# [Product Name] — Product Brief
+
+**Objective:** [One sentence: what is being built and for whom.]
+**Mission Shape:** PRODUCT_BUILD | BOUNDED | RESEARCH_ONLY
+**Risk Level:** LOW | MEDIUM | HIGH
+
+## Objective and Target User
+
+- **Primary user:** [Who they are.]
+- **Core job-to-be-done:** [The one job this product must nail.]
+
+## Assumptions and Non-Goals
+
+**Assumptions** (every material choice made without explicit user input):
+
+- [Assumption — why it is conservative/reversible.]
+
+**Non-goals** (explicitly NOT being built):
+
+- [Non-goal.]
+
+## Tech Stack Decision Log
+
+| Concern | Choice | Rationale |
+|---|---|---|
+| Framework | [choice] | [why — reference §6.5 defaults where applied] |
+| Language | [choice] | [why] |
+| Styling | [choice] | [why] |
+| Database / persistence | [choice] | [why] |
+| ORM | [choice] | [why] |
+| Auth | [choice] | [why] |
+| Testing | [choice] | [why] |
+
+## Screens / Routes / API Surfaces
+
+- `[route or surface]` — [purpose]
+
+## Core User Flows
+
+### Flow 1: [Name]
+
+1. [Step — happy path.]
+2. [Step.]
+
+**Failure paths:** [What happens on error / invalid input / timeout.]
+
+## Design Direction (greenfield UI)
+
+- **Chosen direction:** [typography, color system, layout language, mood.]
+- **Why it won:** [over which alternatives.]
+
+## UX / Screen Spec
+
+### [Screen name] (`[route]`)
+
+- **Layout:** [description]
+- **Components:** [list]
+- **States:** loading / error / empty / populated — [each described]
+- **Responsive:** [behavior at mobile / desktop]
+- **Navigation:** [entry and exit points]
+
+## Data Model
+
+- **[Entity]** — [key fields, relationships]
+
+**Migration strategy:** [approach]
+
+## Security Model
+
+- **Auth strategy:** [sessions/JWT, storage, expiry]
+- **Input validation:** [approach, library]
+- **CORS policy:** [policy]
+- **Secrets:** [where they live, how they are loaded]
+
+## Environment Variable Manifest
+
+| Name | Purpose | Example | Required |
+|---|---|---|---|
+| `[VAR]` | [purpose] | `[example]` | yes/no |
+
+## Architecture and File Ownership Map
+
+```
+[directory structure]
+```
+
+| Area | Owner |
+|---|---|
+| `[path]` | wolverine-1 \| wolverine-2 \| storm-ui |
+
+## Milestones
+
+### Milestone 1: [Name]
+
+- **Acceptance criteria:** [concrete, measurable — not "it works correctly"]
+- **Verify:** `[exact command or manual check]`
+
+## Tests and Verification Commands
+
+- `[command]` — [what passing means]
+
+## Production Readiness Criteria
+
+- [§9.5 checklist items that apply to this build.]
+
+## Risks, Approval Gates, Rollback
+
+- **Risks:** [risk — mitigation]
+- **Approval gates:** [gate, or None]
+- **Rollback / recovery:** [how to undo if execution fails]

package/.cerebro/templates/project-context.md

@@ -0,0 +1,64 @@
+# Cerebro Project Context
+
+**Indexed At:** [timestamp]
+**Repository:** [name or path]
+
+## Stack
+
+- Language/runtime:
+- Frameworks:
+- Package manager:
+- Test framework:
+- Build system:
+
+## Entrypoints
+
+- Plugin/source:
+- CLI/scripts:
+- OpenCode agents:
+- OpenCode commands:
+- Runtime state:
+- Configuration:
+
+## Commands
+
+- Install:
+- Test:
+- Focused test:
+- Lint:
+- Typecheck:
+- Build:
+- Run/dev:
+
+## Architecture
+
+- [Major subsystem] - [purpose and relevant files]
+- [Major subsystem] - [purpose and relevant files]
+- `.opencode/` - active OpenCode agents, commands, and plugin bridge when this is an OpenCode/Cerebro project
+- `.cerebro/` - plans, run manifests, task ledgers, mailbox logs, checkpoints, notepads, and validators
+
+## Conventions
+
+- File organization:
+- Naming:
+- Error handling:
+- Testing:
+- Model routing:
+- UI/styling:
+
+## Risky Areas
+
+- [Area] - [why risky and what to verify]
+
+## Agent Notes
+
+- Prefer:
+- Avoid:
+- Open questions:
+
+## Read First
+
+1. `AGENTS.md` - repository-level operating rules, if present
+2. `.cerebro/cerebro-identity.md` - Cerebro runtime identity and role routing, if present
+3. `.cerebro/opencode/model-routing.md` - OpenCode model slots, if present
+4. Relevant `.opencode/agents/*.md` and `.opencode/commands/*.md`, if present

package/.cerebro/templates/requirements-brief.md

@@ -0,0 +1,67 @@
+# [Product Name] — Requirements Brief
+
+**Prepared by:** Cypher (Business Analyst)
+**Request:** [The user's original request, verbatim or lightly cleaned.]
+**Mission Shape:** PRODUCT_BUILD | BOUNDED | RESEARCH_ONLY
+
+## Problem Statement
+
+[2–3 sentences: what problem this solves and why it matters. The WHY behind the request.]
+
+## Target Users
+
+- **Primary user:** [Who they are, their context, their level of expertise.]
+- **Secondary users:** [If any, or None.]
+
+## Jobs To Be Done
+
+- **Core job:** [The one job this product must nail — "When ___, I want to ___, so I can ___".]
+- **Supporting jobs:** [Other jobs, ranked.]
+
+## User Stories
+
+| # | As a… | I want to… | So that… | Priority |
+|---|---|---|---|---|
+| 1 | [user] | [action] | [outcome] | must / should / could |
+
+## Acceptance Criteria
+
+Per story or per capability — concrete, testable, pass/fail (never "it works correctly"):
+
+- **Story 1:**
+  - [ ] [Given … when … then …]
+  - [ ] [Edge case: empty / error / boundary behavior]
+
+## Business Rules
+
+- [Rule the product must enforce — validation, limits, permissions, state transitions.]
+
+## Success Metrics
+
+- [How we know the product succeeds — measurable where possible.]
+
+## Scope
+
+**In scope:**
+- [Capability.]
+
+**Out of scope / non-goals:**
+- [Explicitly NOT being built.]
+
+## Assumptions
+
+Conservative, reversible choices made without explicit user input:
+
+- [Assumption — why it is safe.]
+
+## Open Questions
+
+**Blocking (need a user/Cerebro decision before build):**
+- [Question, or None.]
+
+**Non-blocking (safe to proceed, worth confirming):**
+- [Question, or None.]
+
+## Handoff to Professor X
+
+[One paragraph: the essence Professor X needs to design the technical Product Brief. Points him at the must-have stories and the hardest acceptance criteria. Does NOT prescribe HOW.]

package/.cerebro/templates/team-run.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "run_id": "20260522-000000-example-run",
+  "command": "/to-me-my-x-men",
+  "status": "planning",
+  "lead": "cerebro",
+  "team_name": "replace-with-team-name",
+  "objective": "replace with the user objective",
+  "risk_level": "LOW",
+  "started_at": "2026-05-22T00:00:00Z",
+  "updated_at": "2026-05-22T00:00:00Z",
+  "teammates": [],
+  "ownership": [],
+  "mailbox_decisions": [],
+  "approvals": [],
+  "verification": [],
+  "cleanup": {
+    "team_stopped": false,
+    "pending_todos_clear": false,
+    "notes": ""
+  }
+}