codexkit 1.0.0

package/.codex/scripts/start_bead.sh

@@ -0,0 +1,129 @@
+#!/bin/bash
+set -euo pipefail
+# Script: start_bead
+# Claim a bead and prepare a branch/workspace for execution.
+
+PROJECT_ROOT="${CODEXKIT_PROJECT_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+BEAD_ID="${1:-}"
+USE_CURRENT_BRANCH=false
+
+if [[ -z "$BEAD_ID" ]]; then
+  echo "Usage: $0 <bead-id> [--use-current-branch]" >&2
+  exit 1
+fi
+shift || true
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --use-current-branch)
+      USE_CURRENT_BRANCH=true
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      echo "Usage: $0 <bead-id> [--use-current-branch]" >&2
+      exit 1
+      ;;
+  esac
+  shift || true
+done
+
+if ! command -v br >/dev/null 2>&1; then
+  echo "Missing dependency: br" >&2
+  exit 1
+fi
+
+ARTIFACT_DIR="$PROJECT_ROOT/.beads/artifacts/$BEAD_ID"
+PRD_FILE="$ARTIFACT_DIR/prd.md"
+
+if [[ ! -f "$PRD_FILE" ]]; then
+  echo "Missing PRD file: $PRD_FILE" >&2
+  exit 1
+fi
+
+if ! grep -q '[^[:space:]]' "$PRD_FILE"; then
+  echo "PRD file is empty: $PRD_FILE" >&2
+  exit 1
+fi
+
+dirty_output="$(git -C "$PROJECT_ROOT" status --porcelain)"
+if [[ -n "$dirty_output" ]]; then
+  while IFS= read -r dirty_line; do
+    [[ -z "$dirty_line" ]] && continue
+    dirty_path="${dirty_line:3}"
+    if [[ "$dirty_path" != .beads/* ]]; then
+      echo "Workspace is dirty outside .beads/. Commit or stash changes before starting a bead." >&2
+      exit 1
+    fi
+  done <<< "$dirty_output"
+fi
+
+metadata_json="$(cd "$PROJECT_ROOT" && br show --json "$BEAD_ID" 2>/dev/null || true)"
+if [[ -z "$metadata_json" ]]; then
+  echo "Unable to load bead metadata for: $BEAD_ID" >&2
+  exit 1
+fi
+
+eval "$(
+  python3 - "$metadata_json" <<'PY'
+import json
+import re
+import shlex
+import sys
+
+raw = sys.argv[1]
+data = json.loads(raw)
+issue = data
+if isinstance(data, dict) and isinstance(data.get("issue"), dict):
+    issue = data["issue"]
+elif isinstance(data, dict) and isinstance(data.get("issues"), list) and data["issues"]:
+    issue = data["issues"][0]
+elif isinstance(data, list) and data:
+    issue = data[0]
+
+title = issue.get("title") or issue.get("name") or "untitled"
+issue_type = issue.get("issue_type") or issue.get("type") or "task"
+status = issue.get("status") or "unknown"
+
+slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
+if not slug:
+    slug = "task"
+
+print(f"BEAD_TITLE={shlex.quote(title)}")
+print(f"BEAD_TYPE={shlex.quote(issue_type)}")
+print(f"BEAD_STATUS={shlex.quote(status)}")
+print(f"BEAD_SLUG={shlex.quote(slug)}")
+PY
+)"
+
+if [[ "$BEAD_STATUS" != "in_progress" ]]; then
+  (cd "$PROJECT_ROOT" && br update "$BEAD_ID" --status in_progress >/dev/null)
+fi
+
+BRANCH_NAME="$(git -C "$PROJECT_ROOT" branch --show-current)"
+TARGET_BRANCH="$BRANCH_NAME"
+if ! $USE_CURRENT_BRANCH; then
+  case "$BEAD_TYPE" in
+    feature) prefix="feat" ;;
+    bug) prefix="fix" ;;
+    task) prefix="task" ;;
+    epic) prefix="epic" ;;
+    *) prefix="task" ;;
+  esac
+  TARGET_BRANCH="$prefix/$BEAD_ID-$BEAD_SLUG"
+  if [[ "$BRANCH_NAME" != "$TARGET_BRANCH" ]]; then
+    if git -C "$PROJECT_ROOT" show-ref --verify --quiet "refs/heads/$TARGET_BRANCH"; then
+      git -C "$PROJECT_ROOT" checkout "$TARGET_BRANCH" >/dev/null
+    else
+      git -C "$PROJECT_ROOT" checkout -b "$TARGET_BRANCH" >/dev/null
+    fi
+  fi
+fi
+
+mkdir -p "$ARTIFACT_DIR"
+touch "$ARTIFACT_DIR/progress.txt"
+
+echo "bead=$BEAD_ID"
+echo "type=$BEAD_TYPE"
+echo "status=in_progress"
+echo "branch=$(git -C "$PROJECT_ROOT" branch --show-current)"
+echo "prd=$PRD_FILE"

package/.codex/scripts/sync_bead_context.sh

@@ -0,0 +1,288 @@
+#!/bin/bash
+set -euo pipefail
+# Script: sync_bead_context
+# Summarize a bead's raw artifacts into durable repo context.
+
+PROJECT_ROOT="${CODEXKIT_PROJECT_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+BEAD_ID="${1:-}"
+
+if [[ -z "$BEAD_ID" ]]; then
+  echo "Usage: $0 <bead-id>" >&2
+  exit 1
+fi
+
+ARTIFACT_DIR="$PROJECT_ROOT/.beads/artifacts/$BEAD_ID"
+SUMMARY_DIR="$PROJECT_ROOT/.codex/memory/research/beads"
+SUMMARY_FILE="$SUMMARY_DIR/$BEAD_ID.md"
+WORKLOG_FILE="$PROJECT_ROOT/.codex/context/worklog.md"
+
+if [[ ! -d "$ARTIFACT_DIR" ]]; then
+  echo "Missing artifact directory: $ARTIFACT_DIR" >&2
+  exit 1
+fi
+
+mkdir -p "$SUMMARY_DIR"
+mkdir -p "$(dirname "$WORKLOG_FILE")"
+
+metadata_json=""
+if command -v br >/dev/null 2>&1; then
+  if metadata_json="$(cd "$PROJECT_ROOT" && br show --json "$BEAD_ID" 2>/dev/null)"; then
+    :
+  else
+    metadata_json=""
+  fi
+fi
+
+old_hash=""
+if [[ -f "$SUMMARY_FILE" ]]; then
+  old_hash="$(shasum -a 256 "$SUMMARY_FILE" | cut -d' ' -f1)"
+fi
+
+tmp_summary="$(mktemp)"
+cleanup() {
+  rm -f "$tmp_summary"
+}
+trap cleanup EXIT
+
+python3 - "$BEAD_ID" "$PROJECT_ROOT" "$ARTIFACT_DIR" "$metadata_json" > "$tmp_summary" <<'PY'
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+bead_id, project_root, artifact_dir, metadata_json = sys.argv[1:]
+artifact_path = Path(artifact_dir)
+
+
+def load_metadata(raw: str):
+    if not raw.strip():
+        return {}
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    if isinstance(data, dict):
+        if "id" in data:
+            return data
+        if isinstance(data.get("issue"), dict):
+            return data["issue"]
+        if isinstance(data.get("issues"), list) and data["issues"]:
+            first = data["issues"][0]
+            if isinstance(first, dict):
+                return first
+    if isinstance(data, list) and data and isinstance(data[0], dict):
+        return data[0]
+    return {}
+
+
+def read_text(path: Path) -> str:
+    if not path.exists() or not path.is_file():
+        return ""
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def extract_section(text: str, heading: str) -> str:
+    pattern = re.compile(
+        rf"^##+\s+{re.escape(heading)}\s*$\n(.*?)(?=^##+\s+|\Z)",
+        re.MULTILINE | re.DOTALL,
+    )
+    match = pattern.search(text)
+    if not match:
+        return ""
+    return match.group(1).strip()
+
+
+def bulletize(text: str, fallback: str) -> list[str]:
+    lines = []
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line.startswith(("- ", "* ")):
+            lines.append(line)
+        elif re.match(r"^\d+\.\s+", line):
+            lines.append(f"- {re.sub(r'^\d+\.\s+', '', line)}")
+    if lines:
+        return lines
+    plain = " ".join(part.strip() for part in text.splitlines() if part.strip())
+    if plain:
+        return [f"- {plain}"]
+    return [fallback]
+
+
+def first_paragraph(text: str, fallback: str) -> str:
+    if not text.strip():
+        return fallback
+    body = []
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line:
+            if body:
+                break
+            continue
+        if line.startswith("#"):
+            continue
+        body.append(line)
+    if body:
+        return " ".join(body)
+    return fallback
+
+
+def trim_paragraph(text: str, fallback: str) -> str:
+    cleaned = " ".join(line.strip() for line in text.splitlines() if line.strip())
+    return cleaned or fallback
+
+
+metadata = load_metadata(metadata_json)
+title = metadata.get("title") or bead_id
+status = metadata.get("status") or "unknown"
+issue_type = metadata.get("issue_type") or metadata.get("type") or "unknown"
+description = metadata.get("description") or ""
+
+prd_text = read_text(artifact_path / "prd.md")
+research_text = read_text(artifact_path / "research.md")
+design_text = read_text(artifact_path / "design.md")
+notes_text = read_text(artifact_path / "notes.md")
+progress_text = read_text(artifact_path / "progress.txt")
+
+handoff_dir = artifact_path / "handoffs"
+handoff_files = sorted(handoff_dir.glob("*")) if handoff_dir.exists() else []
+latest_handoff_text = ""
+latest_handoff_name = ""
+if handoff_files:
+    latest_handoff = handoff_files[-1]
+    latest_handoff_name = latest_handoff.name
+    latest_handoff_text = read_text(latest_handoff)
+
+problem = extract_section(prd_text, "Problem Statement")
+if not problem:
+    problem = description
+problem = trim_paragraph(problem, "No durable problem statement captured yet.")
+
+done_text = extract_section(latest_handoff_text, "Done")
+in_progress_text = extract_section(latest_handoff_text, "In Progress")
+remaining_text = extract_section(latest_handoff_text, "Remaining")
+progress_lines = [line.strip() for line in progress_text.splitlines() if line.strip()]
+recent_progress = progress_lines[-3:] if progress_lines else []
+
+outcome_lines = []
+if done_text:
+    outcome_lines.extend(bulletize(done_text, "- No completed work recorded"))
+if in_progress_text:
+    outcome_lines.extend(bulletize(in_progress_text, "- No in-progress snapshot recorded"))
+if not outcome_lines and recent_progress:
+    outcome_lines.extend(f"- {line.lstrip('- ').strip()}" for line in recent_progress)
+if not outcome_lines:
+    outcome_lines = [f"- Current bead status: {status}"]
+
+decisions_text = extract_section(latest_handoff_text, "Decisions")
+if decisions_text:
+    decision_lines = bulletize(decisions_text, "- No durable decisions recorded")
+else:
+    proposed_solution = extract_section(prd_text, "Proposed Solution")
+    if proposed_solution:
+        decision_lines = bulletize(proposed_solution, "- No durable decisions recorded")
+    elif design_text:
+        decision_lines = bulletize(first_paragraph(design_text, ""), "- No durable decisions recorded")
+    else:
+        decision_lines = ["- No durable decisions recorded"]
+
+affected_text = extract_section(prd_text, "Affected Files")
+files_touched_text = extract_section(latest_handoff_text, "Files Touched")
+file_lines: list[str] = []
+for chunk in (affected_text, files_touched_text):
+    for line in bulletize(chunk, ""):
+        if line != "":
+            file_lines.append(line)
+if not file_lines:
+    file_lines = ["- No concrete file list recorded"]
+
+follow_up_text = remaining_text or extract_section(prd_text, "Open Questions")
+if not follow_up_text and notes_text:
+    follow_up_text = first_paragraph(notes_text, "")
+follow_up_lines = bulletize(follow_up_text, "- No follow-up items recorded")
+
+keyword_parts = [bead_id, title, issue_type]
+for line in file_lines:
+    path_part = re.sub(r"^- ", "", line).split(" ", 1)[0]
+    if "/" in path_part or "." in path_part:
+        keyword_parts.append(path_part)
+keywords = []
+seen = set()
+for part in keyword_parts:
+    for token in re.split(r"[^A-Za-z0-9._/-]+", part):
+        token = token.strip().lower()
+        if len(token) < 3:
+            continue
+        if token not in seen:
+            seen.add(token)
+            keywords.append(token)
+
+source_artifacts = []
+for name in ("prd.md", "research.md", "design.md", "notes.md", "progress.txt"):
+    if (artifact_path / name).exists():
+        source_artifacts.append(f".beads/artifacts/{bead_id}/{name}")
+if latest_handoff_name:
+    source_artifacts.append(f".beads/artifacts/{bead_id}/handoffs/{latest_handoff_name}")
+
+print(f"# Bead Summary: {bead_id} — {title}")
+print()
+print("## Bead")
+print()
+print(f"- ID: `{bead_id}`")
+print(f"- Title: {title}")
+print(f"- Status: {status}")
+print(f"- Type: {issue_type}")
+print()
+print("## Problem")
+print()
+print(problem)
+print()
+print("## Outcome")
+print()
+for line in outcome_lines:
+    print(line)
+print()
+print("## Key Decisions")
+print()
+for line in decision_lines:
+    print(line)
+print()
+print("## Files/Areas Affected")
+print()
+for line in file_lines:
+    print(line)
+print()
+print("## Follow-ups")
+print()
+for line in follow_up_lines:
+    print(line)
+print()
+print("## Keywords")
+print()
+print("- " + ", ".join(keywords) if keywords else "- No keywords extracted")
+print()
+print("## Source Artifacts")
+print()
+for path in source_artifacts:
+    print(f"- `{path}`")
+if not source_artifacts:
+    print("- No source artifacts found beyond the bead directory")
+PY
+
+mv "$tmp_summary" "$SUMMARY_FILE"
+
+new_hash="$(shasum -a 256 "$SUMMARY_FILE" | cut -d' ' -f1)"
+if [[ "$old_hash" != "$new_hash" ]]; then
+  timestamp="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  if [[ ! -f "$WORKLOG_FILE" ]]; then
+    {
+      echo "# Worklog"
+      echo
+    } > "$WORKLOG_FILE"
+  fi
+  echo "- **[$timestamp]** Synced bead context for \`$BEAD_ID\` → \`.codex/memory/research/beads/$BEAD_ID.md\`" >> "$WORKLOG_FILE"
+fi
+
+echo "$SUMMARY_FILE"

package/.codex/scripts/validate_memory_docs.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+set -euo pipefail
+
+ROOT_DIR="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+PASS=0
+FAIL=0
+
+check() {
+  local desc="$1"; shift
+  if "$@" >/dev/null 2>&1; then
+    echo "  PASS  $desc"
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL  $desc"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+require_heading() {
+  local file="$1" pattern="$2"
+  grep -Eq "$pattern" "$file"
+}
+
+echo "=== Memory Doc Validation ==="
+
+check "project/user.md has Preferences section" require_heading "$ROOT_DIR/memory/project/user.md" '^## Preferences'
+check "project/tech-stack.md has Verification Commands section" require_heading "$ROOT_DIR/memory/project/tech-stack.md" '^## Verification Commands'
+check "project/project.md has Vision section" require_heading "$ROOT_DIR/memory/project/project.md" '^## Vision'
+check "project/roadmap.md has Current Phase section" require_heading "$ROOT_DIR/memory/project/roadmap.md" '^## Current Phase'
+check "project/state.md has Next Actions section" require_heading "$ROOT_DIR/memory/project/state.md" '^## Next Actions'
+check "project/state.md has Blockers section" require_heading "$ROOT_DIR/memory/project/state.md" '^## Blockers'
+check "project/gotchas.md is non-empty" test "$(wc -l < "$ROOT_DIR/memory/project/gotchas.md" | tr -d ' ')" -ge 3
+check "context/session-context.md has Current Focus section" require_heading "$ROOT_DIR/context/session-context.md" '^## Current Focus'
+check "context/session-context.md has Next Actions section" require_heading "$ROOT_DIR/context/session-context.md" '^## Next Actions'
+check "context/decision-log.md has Decisions section" require_heading "$ROOT_DIR/context/decision-log.md" '^## Decisions'
+
+if [ "$FAIL" -gt 0 ]; then
+  echo
+  echo "Memory doc validation failed"
+  exit 1
+fi
+
+echo
+echo "Memory doc validation passed ($PASS checks)"

package/.codex/scripts/verify_bead.sh

@@ -0,0 +1,154 @@
+#!/bin/bash
+set -euo pipefail
+# Script: verify_bead
+# Run project gates and PRD Verify commands, then record a PASS stamp.
+
+PROJECT_ROOT="${CODEXKIT_PROJECT_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+BEAD_ID="${1:-}"
+FULL=false
+NO_CACHE=false
+
+if [[ -z "$BEAD_ID" ]]; then
+  echo "Usage: $0 <bead-id> [--full] [--no-cache]" >&2
+  exit 1
+fi
+shift || true
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --full)
+      FULL=true
+      ;;
+    --no-cache)
+      NO_CACHE=true
+      ;;
+    --quick)
+      ;;
+    --fix)
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      echo "Usage: $0 <bead-id> [--full] [--no-cache]" >&2
+      exit 1
+      ;;
+  esac
+  shift || true
+done
+
+if ! command -v br >/dev/null 2>&1; then
+  echo "Missing dependency: br" >&2
+  exit 1
+fi
+
+ARTIFACT_DIR="$PROJECT_ROOT/.beads/artifacts/$BEAD_ID"
+PRD_FILE="$ARTIFACT_DIR/prd.md"
+VERIFY_LOG="$PROJECT_ROOT/.beads/verify.log"
+
+if [[ ! -f "$PRD_FILE" ]]; then
+  echo "Missing PRD file: $PRD_FILE" >&2
+  exit 1
+fi
+
+status_json="$(cd "$PROJECT_ROOT" && br show --json "$BEAD_ID" 2>/dev/null || true)"
+if [[ -z "$status_json" ]]; then
+  echo "Unable to load bead metadata for: $BEAD_ID" >&2
+  exit 1
+fi
+
+BEAD_STATUS="$(
+  python3 - "$status_json" <<'PY'
+import json
+import sys
+
+raw = sys.argv[1]
+data = json.loads(raw)
+issue = data
+if isinstance(data, dict) and isinstance(data.get("issue"), dict):
+    issue = data["issue"]
+elif isinstance(data, dict) and isinstance(data.get("issues"), list) and data["issues"]:
+    issue = data["issues"][0]
+elif isinstance(data, list) and data:
+    issue = data[0]
+
+print(issue.get("status") or "unknown")
+PY
+)"
+
+if [[ "$BEAD_STATUS" != "in_progress" && "$BEAD_STATUS" != "closed" ]]; then
+  echo "Bead must be in_progress or closed to verify: $BEAD_STATUS" >&2
+  exit 1
+fi
+
+CURRENT_STAMP="$(
+  cd "$PROJECT_ROOT" &&
+  printf '%s\n%s\n%s' \
+    "$(git rev-parse HEAD)" \
+    "$(git diff HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx')" \
+    "$(git ls-files --others --exclude-standard -- '*.ts' '*.tsx' '*.js' '*.jsx' | xargs cat 2>/dev/null)" \
+    | shasum -a 256 | cut -d' ' -f1
+)"
+LAST_STAMP="$(tail -1 "$VERIFY_LOG" 2>/dev/null | awk '{print $1}' || true)"
+
+if ! $NO_CACHE && ! $FULL && [[ -n "$LAST_STAMP" && "$CURRENT_STAMP" = "$LAST_STAMP" ]]; then
+  echo "cached-pass=$CURRENT_STAMP"
+  exit 0
+fi
+
+run_npm_script_if_present() {
+  local script_name="$1"
+  if [[ ! -f "$PROJECT_ROOT/package.json" ]]; then
+    return 0
+  fi
+
+  local has_script
+  has_script="$(
+    python3 - "$PROJECT_ROOT/package.json" "$script_name" <<'PY'
+import json
+import sys
+
+package_json = sys.argv[1]
+script_name = sys.argv[2]
+with open(package_json, encoding="utf-8") as handle:
+    data = json.load(handle)
+print("yes" if script_name in data.get("scripts", {}) else "no")
+PY
+  )"
+
+  if [[ "$has_script" = "yes" ]]; then
+    (cd "$PROJECT_ROOT" && npm run "$script_name" >/dev/null)
+  fi
+}
+
+run_verify_commands() {
+  python3 - "$PRD_FILE" <<'PY'
+import re
+import shlex
+import sys
+from pathlib import Path
+
+prd_path = Path(sys.argv[1])
+text = prd_path.read_text(encoding="utf-8", errors="replace")
+for raw_line in text.splitlines():
+    match = re.match(r"^\s*-\s*Verify:\s*(.+?)\s*$", raw_line)
+    if match:
+        print(match.group(1))
+PY
+}
+
+run_npm_script_if_present typecheck
+run_npm_script_if_present lint
+run_npm_script_if_present test
+run_npm_script_if_present build
+
+while IFS= read -r verify_cmd; do
+  [[ -z "$verify_cmd" ]] && continue
+  (cd "$PROJECT_ROOT" && bash -lc "$verify_cmd" >/dev/null)
+done < <(run_verify_commands)
+
+mkdir -p "$(dirname "$VERIFY_LOG")"
+echo "$CURRENT_STAMP $(date -u +%Y-%m-%dT%H:%M:%SZ) PASS" >> "$VERIFY_LOG"
+(cd "$PROJECT_ROOT" && br comments add "$BEAD_ID" "Verification: PASS - gates and Verify commands succeeded" >/dev/null)
+
+echo "verified=$BEAD_ID"
+echo "stamp=$CURRENT_STAMP"
+echo "log=$VERIFY_LOG"