backstage companion

Anti-drift protocol script. Ensures parity between docs and system. Triggers: 'bom dia PROJECT' / 'good morning PROJECT' (load project context with health checks)

# Backstage Skill

**Nickname:** `backstage:`

**Objective:** Universal project status management for AI-assisted development. Ensures documentation matches reality before every commit.

---

## ⚠️ Security Notice

**This is an admin tool with elevated privileges:**

- **Executes checks from global path** (`$HOME/Documents/backstage/backstage/checks/global/`)
- **Pulls remote code** from GitHub (https://github.com/nonlinear/backstage)
- **Modifies project files** (README, ROADMAP, CHANGELOG with mermaid diagrams)
- **Rsyncs updates** when using `update backstage` trigger

**Intended for:**
- Personal use (you control the upstream repo)
- Trusted teams (shared backstage protocol repo)

**Not recommended for:**
- Untrusted third-party projects
- Public/open-source projects with unknown contributors

**Mitigations in place:**
- User confirmation before applying updates
- Git history (all changes committed, revertable)
- Symlink detection (admin mode auto-updates)

**Use at your own risk.** Review `update-backstage.sh` and `checks.sh` before running.

---

## 🔴 Why This Skill Exists (Anti-Drift)

**Backstage-skill = ANTI-DRIFT:**
- ✅ Force context awareness (project/epic)
- ✅ Health checks prevent chaos
- ✅ Architecture-first workflow
- ✅ Roadmap visibility = no surprises

**WITHOUT IT:**  
Work happens outside backstage → drift → broken trust → triple metabolic cost

**WITH IT:**  
"good morning X" → automatic context load → work inside boundaries → paridade maintained

---

**The Metabolic Cost Problem:**

Without backstage, delegation costs **triple**:
1. The work itself
2. Explicating methodology (ethics, preferences, protocols)
3. Defining WHERE that learning gets stored (VISION? SOUL? SKILL? memory?)

This is **exhausting** for the human.

**Investment is worth it ONLY IF plateau is reached:**
- Human teaches ONCE → AI internalizes
- Each session: READ context files → act according to ethics
- Each session: LESS explanation needed
- Plateau = Human delegates, AI executes without supervision

**This skill enforces stabilization.**  
Force context awareness (project/epic/design architecture) to prevent drift.  
**3x work becomes 1x work.**

---

## Policies & Checks Enforcement

**Backstage-skill enforces ALL rules in checks/ (deterministic + interpretive, global + local).**

### Enforcement Model

```mermaid
flowchart TD
    READ_CHK["Read checks/<br/>global + local<br/>[Deterministic .sh + Interpretive .md]"]
    
    CONFLICT{Conflict?}
    MERGE[Merge compatible rules]
    LOCAL[Local wins]
    
    AI["AI interprets .md checks<br/>[Contextual enforcement]"]
    SH["Bash executes .sh checks<br/>[Deterministic validation]"]
    
    AI_ACT[✅ Enforce or discuss]
    AI_AMBIG[⚠️ Ask user]
    
    SH_OK[✅ All checks pass]
    SH_FAIL[❌ Checks failed]
    
    REPORT["Report:<br/>📋 Interpretive (always ✅)<br/>🔍 Deterministic (✅/❌)"]
    
    READ_CHK --> CONFLICT
    CONFLICT -->|No| MERGE
    CONFLICT -->|Yes| LOCAL
    MERGE --> AI
    MERGE --> SH
    LOCAL --> AI
    LOCAL --> SH
    
    AI -->|Clear| AI_ACT
    AI -->|Ambiguous| AI_AMBIG
    
    SH -->|Pass| SH_OK
    SH -->|Fail| SH_FAIL
    
    AI_ACT --> REPORT
    AI_AMBIG --> REPORT
    SH_OK --> REPORT
    SH_FAIL --> REPORT
```

**Two enforcement domains:**

1. **Checks (Interpretive)**
   - `checks/global/*.md` = Universal workflow rules
   - `checks/local/*.md` = Project-specific overrides
   - **Enforced by:** AI (reads markdown, interprets context, acts)
   - **Always pass:** AI reads, understands, will act accordingly

2. **Checks (Deterministic)**
   - `checks/global/*.sh` = Universal validation tests
   - `checks/local/*.sh` = Project-specific tests
   - **Enforced by:** Bash (executes shell scripts, exit codes)
   - **Pass or fail:** ✅ (exit 0) or ❌ (exit non-zero)

**Polycentric governance:**
- Global + local rules coexist
- Local wins on conflict
- AI merges when compatible

**Report format:**

```
📋 Interpretive checks:
  ✅ checks/global/branch-workflow.md (read)
  ✅ checks/global/commit-style.md (read)
  ✅ checks/local/dogfooding.md (read)

🔍 Checks (deterministic):
  ✅ checks/global/navigation-block-readme.sh
  ✅ checks/global/semver-changelog.sh
  ❌ checks/local/pre-merge-tasks.sh (incomplete tasks)
```

**Self-contained:** All prompts in SKILL.md (no external prompt files needed).

---

## Mermaid Diagram Generation (Interpretive)

**Purpose:** Automatically generate + propagate ROADMAP diagram to all backstage files.

**Workflow:**

1. **Parse ROADMAP.md** (deterministic - SH):
   ```bash
   parse-roadmap.sh backstage/ROADMAP.md
   # Output: version|status_emoji|name
   ```

2. **Read checks/ diagram rules** (interpretive - AI):
   - `checks/global/navigation-block.md` defines default format (linear graph, all epics, sequential)
   - `checks/local/*.md` can override (gantt, flowchart, or `diagram: none`)
   - Local wins on conflict

3. **Generate mermaid** (interpretive - AI):
   - Apply checks/ rules to parsed data
   - Create mermaid syntax matching specification
   - Example (default):
     ```mermaid
     graph LR
         A[🏗️ v0.1.0 Active Epic] --> B[📋 v0.2.0 Backlog Epic]
     ```

4. **Propagate to all files** (deterministic - SH):
   - Insert after `> 🤖` marker
   - README.md, ROADMAP.md, CHANGELOG.md
   - Remove old diagrams (anti-drift)

**AI Prompt (when running backstage-start/end):**

> Read checks/global/navigation-block.md and checks/local/*.md for diagram rules.
> Run `parse-roadmap.sh` to extract epics.
> Generate mermaid diagram following checks/ rules (prefer local over global).
> Insert diagram after navigation block (`> 🤖`) in all backstage files.
> If local checks say `diagram: none`, skip generation.

**Tools:**
- `parse-roadmap.sh` - Extract version|status|name from ROADMAP.md
- `checks/` - Diagram format rules (type, include/exclude logic, status mapping)

---

## Polycentric Governance (How It Works)

```mermaid
flowchart TD
    GLOBAL_POL[checks/global/*.md<br/>Universal rules]
    LOCAL_POL[checks/local/*.md<br/>Project-specific overrides]
    
    GLOBAL_CHK[checks/global/*.sh<br/>Universal tests]
    LOCAL_CHK[checks/local/*.sh<br/>Project-specific tests]
    
    AI[AI reads checks/]
    BASH[Bash executes checks/]
    CONFLICT{Conflict?}
    
    GLOBAL_POL --> AI
    LOCAL_POL --> AI
    GLOBAL_CHK --> BASH
    LOCAL_CHK --> BASH
    
    AI --> CONFLICT
    CONFLICT -->|Yes| LOCAL_POL
    CONFLICT -->|No| MERGE[Merge rules]
    
    MERGE --> ACTION[Execute workflow]
    LOCAL_POL --> ACTION
    BASH --> ACTION
```

**This skill enforces polycentric governance:**
- Reads ALL `checks/**/*.md` files (global + local)
- Executes ALL `checks/**/*.sh` files (global + local)
- Merges checks when compatible
- Prefers local checks on conflict
- Reports deterministic check results (pass/fail)

**Triggered by:** "good morning", "good night", "backstage start/end", "update backstage"

---

## Workflow Diagram

```mermaid
flowchart TD
    START["Trigger 1️⃣<br/>[SH]"]
    MODE{"Session mode?"}
    
    %% Common enforcement module
    READ_POL["Read checks/<br/>global + local<br/>[AI interprets MD]"]
    EXEC_CHK["Execute checks/<br/>global + local<br/>[Bash runs SH]"]
    
    REPORT["Report 6️⃣<br/>📋 Interpretive (✅)<br/>🔍 Checks (✅/❌)"]
    CHECKS_GATE{"All checks<br/>passed?"}
    
    %% Start Branch
    START_BRANCH["Read README 🤖 block 2️⃣<br/>[MD → AI]"]
    START_FILES["Locate status files 3️⃣<br/>[SH]"]
    START_GIT["Check git branch 4️⃣<br/>[SH]"]
    START_WORK["Analyze changes 5️⃣<br/>[SH]"]
    START_FIX["🛑 STOP: Fix issues<br/>[AI + SH]"]
    START_UPDATE["Update docs 7️⃣<br/>[SH writes MD]"]
    START_REPORT["Developer context 8️⃣<br/>[AI reads MD]"]
    START_PUSH["Push / Groom 9️⃣<br/>[SH]"]
    
    %% End Branch
    END_FIXES["Add fixes to roadmap<br/>[AI writes MD]"]
    END_PUSH["Commit + push<br/>[SH]"]
    END_VICTORY["Victory lap 🏆<br/>[AI reads MD]"]
    END_BODY["Body check ⏸️<br/>[AI prompt]"]
    END_C