refactor(installer): resolve architectural inconsistencies, pyyaml hard check, and migrate reports to tracked paths

scripts/install_mam.sh

@@ -65,7 +65,13 @@ while [ -h "$SOURCE" ]; do
 done
 DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
 SRC_DIR="$(cd "$DIR/.." && pwd)"
-TARGET_DIR="$(mkdir -p "$TARGET_DIR" && cd "$TARGET_DIR" && pwd)"
+
+# Ensure target directory exists
+if [ ! -d "$TARGET_DIR" ]; then
+  log_info "Creating target directory: $TARGET_DIR"
+  mkdir -p "$TARGET_DIR"
+fi
+TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
 
 log_info "Installing MAM skills to target project: $TARGET_DIR"
 log_info "Source directory resolved: $SRC_DIR"
@@ -77,7 +83,7 @@ fi
 
 # 1. Dependency Checks
 log_info "Verifying host dependencies..."
-DEPS=(tmux python3 sqlite3 rsync)
+DEPS=(tmux python3 sqlite3 rsync uuidgen flock)
 MISSING_DEPS=()
 for dep in "${DEPS[@]}"; do
   if ! command -v "$dep" &>/dev/null; then
@@ -91,10 +97,11 @@ if [ ${#MISSING_DEPS[@]} -ne 0 ]; then
   exit 1
 fi
 
-# Check Python PyYAML library
+# Check Python PyYAML library (hard dependency for YAML registry parsing)
 if ! python3 -c "import yaml" &>/dev/null; then
-  log_warn "Python 'pyyaml' package is not installed. Python YAML parsing features may fail."
-  log_warn "Please run: pip install pyyaml"
+  log_error "Python 'pyyaml' package is not installed (hard dependency for session registry)."
+  log_error "Please run: pip install pyyaml"
+  exit 1
 fi
 log_ok "Dependency checks completed."
 
@@ -103,23 +110,32 @@ log_info "Deploying orchestration rules & skills (.agents/)..."
 mkdir -p "$TARGET_DIR/.agents"
 
 # Sync rules and skills, avoiding copying temporary or system files
-# Exclude git histories or internal runtime cache if any
-rsync -a --exclude='.git/' --exclude='reports/' --exclude='*.log' --exclude='__pycache__/' --exclude='*.pyc' "$SRC_DIR/.agents/" "$TARGET_DIR/.agents/"
+# Exclude git histories, reports, logs or internal runtime cache if any
+rsync -a --exclude='.git/' --exclude='/reports/' --exclude='*.log' --exclude='__pycache__/' --exclude='*.pyc' "$SRC_DIR/.agents/" "$TARGET_DIR/.agents/"
 log_ok "Deployed Rules and Skills under target's .agents/"
 
-# 3. Copy AGENTS.md to root
+# 3. Copy AGENTS.md to root or inject guidelines pointer
 log_info "Configuring developer guidelines (AGENTS.md)..."
-if [ -f "$TARGET_DIR/AGENTS.md" ]; then
+AGENTS_FILE="$TARGET_DIR/AGENTS.md"
+MARKER_START="<!-- BEGIN MAM ORCHESTRATION -->"
+MARKER_END="<!-- END MAM ORCHESTRATION -->"
+
+if [ -f "$AGENTS_FILE" ]; then
   if [ "$FORCE" -eq 1 ]; then
-    log_warn "AGENTS.md already exists in target project. Backing up and overwriting..."
-    cp "$TARGET_DIR/AGENTS.md" "$TARGET_DIR/AGENTS.md.bak.$(date +%s)"
-    cp "$SRC_DIR/AGENTS.md" "$TARGET_DIR/AGENTS.md"
+    log_warn "AGENTS.md already exists in target project. Backing up and overwriting (--force)..."
+    cp "$AGENTS_FILE" "$AGENTS_FILE.bak.$(date +%s)"
+    cp "$SRC_DIR/AGENTS.md" "$AGENTS_FILE"
     log_ok "Guidelines overwritten successfully."
   else
-    log_warn "AGENTS.md already exists in target. Skipping copy. Use -f/--force to overwrite."
+    if grep -Fq "$MARKER_START" "$AGENTS_FILE"; then
+      log_ok "MAM orchestration guidelines pointer already exists in AGENTS.md."
+    else
+      echo -e "\n$MARKER_START\n# 🤖 Multi-Agent Orchestration Guidelines\nPlease refer to [.agents/MULTI_AGENT_RULES.md](file://./.agents/MULTI_AGENT_RULES.md) for detailed collaborative rules and state flow constraints.\n$MARKER_END" >> "$AGENTS_FILE"
+      log_ok "Injected MAM guidelines pointer to existing AGENTS.md."
+    fi
   fi
 else
-  cp "$SRC_DIR/AGENTS.md" "$TARGET_DIR/AGENTS.md"
+  cp "$SRC_DIR/AGENTS.md" "$AGENTS_FILE"
   log_ok "Guidelines AGENTS.md copied to project root."
 fi
 
@@ -129,8 +145,8 @@ GITIGNORE="$TARGET_DIR/.gitignore"
 MAM_PATTERN="/.mam/"
 
 if [ -f "$GITIGNORE" ]; then
-  if grep -Fqx "$MAM_PATTERN" "$GITIGNORE"; then
-    log_ok "/.mam/ already registered in target's .gitignore."
+  if grep -Eq '^/?\.mam/?$' "$GITIGNORE"; then
+    log_ok ".mam/ already registered in target's .gitignore."
   else
     echo -e "\n# Multi-Agent Mux (MAM) runtime databases and isolation cache\n$MAM_PATTERN" >> "$GITIGNORE"
     log_ok "Appended /.mam/ registration to .gitignore."
@@ -140,10 +156,6 @@ else
   log_ok "Created .gitignore with /.mam/ exclusion."
 fi
 
-# 5. Initialize runtime reports folder
-mkdir -p "$TARGET_DIR/.mam/reports"
-log_ok "Initialized runtime structures."
-
 # Done
 log_ok "MAM Installation completed successfully!"
 cat <<EOF
@@ -152,7 +164,8 @@ cat <<EOF
 💡 Quick Start Guide:
   1. Initialize a new isolated session:
      $ bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \\
-         --workspace "$TARGET_DIR" --agent claude --role developer --isolate
+         --workspace "$TARGET_DIR" --agent claude --role developer --isolate \\
+         --tmux-server multi-agent-mux
 
   2. Attach to the running session:
      $ tmux -L multi-agent-mux attach -t <session_name>