popeye-cli 1.9.4 → 1.10.0

package/skills/CONSENSUS_PACKET_SCHEMA.md

@@ -0,0 +1,166 @@
+# CONSENSUS PACKET SCHEMA
+Version: 1.0
+Purpose: Structured record of Reviewer votes and Arbitrator decisions.
+
+Consensus is computed from this packet.
+
+---
+
+# 1. Required Top-Level Fields
+
+1. metadata
+2. plan_packet_reference
+3. reviewer_votes
+4. consensus_rules
+5. consensus_result
+6. arbitrator_result (if applicable)
+7. final_status
+
+---
+
+# 2. Field Definitions
+
+## 2.1 metadata
+
+- consensus_id (UUID)
+- timestamp
+- phase
+- target_artifact
+
+---
+
+## 2.2 plan_packet_reference
+
+- packet_id
+- version
+- hash (optional but recommended)
+
+Must match Plan Packet exactly.
+No voting on outdated packets allowed.
+
+---
+
+## 2.3 reviewer_votes
+
+Array of structured votes:
+
+Each vote MUST contain:
+
+- reviewer_id
+- verdict (APPROVE / APPROVE_WITH_MINOR_CHANGES / REJECT / BLOCKED)
+- score (0–100)
+- blocking_issues[]
+- non_blocking_issues[]
+- hallucination_flags[]
+- constitution_violations[]
+- confidence_level (Low / Medium / High)
+
+---
+
+## 2.4 consensus_rules
+
+Example:
+
+- required_threshold: 95%
+- minimum_reviewers: 2
+- reject_if_any_hallucination: true
+- reject_if_blocking_issue: true
+
+Rules must be explicit.
+No implicit assumptions.
+
+---
+
+## 2.5 consensus_result
+
+Computed fields:
+
+- total_reviewers
+- approvals
+- rejections
+- approval_percentage
+- blocking_issue_count
+- hallucination_count
+- constitution_violation_count
+
+Must be mechanically computable.
+
+---
+
+## 2.6 arbitrator_result (if triggered)
+
+Required if:
+
+- Approval percentage < threshold
+- Reviewers conflict
+- Hallucination flags present
+- Blocking issues exist
+
+Must include:
+
+- final_verdict
+- convergence_summary
+- merged_patch (if any)
+- rejected_items
+- required_revisions
+- dispatcher_next_action
+
+---
+
+## 2.7 final_status
+
+One of:
+
+- APPROVED
+- APPROVED_WITH_PATCH
+- REJECTED
+- BLOCKED
+- REVISION_REQUIRED
+
+No ambiguous states allowed.
+
+---
+
+# 3. Automatic Consensus Failure Conditions
+
+Consensus fails automatically if:
+
+- Any reviewer flags hallucination AND evidence confirms it
+- Any blocking issue remains unresolved
+- Approval percentage < required threshold
+- Constitution violation exists
+
+---
+
+# 4. Consensus Success Conditions
+
+Consensus succeeds if:
+
+- Approval percentage ≥ threshold
+- No unresolved blocking issues
+- No confirmed hallucinations
+- Constitution compliance confirmed
+
+---
+
+# 5. Revision Flow
+
+If final_status = REVISION_REQUIRED:
+
+Dispatcher must:
+1. Update Plan Packet
+2. Increment version
+3. Re-run full review cycle
+
+Partial voting not allowed.
+
+---
+
+# 6. Immutable Record Rule
+
+Consensus Packet must be stored and never mutated.
+New version requires new packet_id.
+
+---
+
+End of Schema.

package/skills/DB_EXPERT.md

@@ -0,0 +1,106 @@
+# Skill: DATABASE EXPERT
+Role Type: Persistence Authority
+Authority Level: Data Ownership
+
+---
+
+## Objective
+
+Design, validate, and enforce database schema integrity, migrations, constraints,
+indexes, and transactional correctness.
+
+DB Expert owns the truth of persistence.
+
+---
+
+## Primary Responsibilities
+
+- Define schema
+- Define migrations
+- Define constraints (FK, uniqueness, indexes)
+- Define transaction boundaries
+- Define data normalization strategy
+- Define seed strategy
+- Define rollback strategy
+- Define performance indexes
+- Define multi-tenant data isolation (if applicable)
+
+---
+
+## Non-Responsibilities
+
+- Does NOT implement business logic
+- Does NOT design API routes
+- Does NOT implement UI
+- Does NOT override architecture
+
+---
+
+## Required Inputs
+
+- Architecture document
+- Master Plan
+- Data flow definitions
+- Performance requirements
+
+---
+
+## Required Outputs
+
+### 1. Schema Definition
+- Tables
+- Fields
+- Types
+- Relationships
+- Constraints
+
+### 2. Migration Plan
+- Migration files
+- Rollback plan
+- Order of execution
+
+### 3. Index Strategy
+- Explicit index definitions
+- Query performance considerations
+
+---
+
+## Evidence Requirements
+
+- File path of schema
+- File path of migration files
+- Explicit index definitions
+- ORM model references (if applicable)
+
+---
+
+## Validation Checklist
+
+- All entities from Master Plan mapped
+- All foreign keys defined
+- No orphan tables
+- Indexes for query-heavy paths
+- No undefined fields
+- Migration order deterministic
+
+---
+
+## Anti-Shortcut Rules
+
+- No implicit relationships
+- No missing constraints
+- No skipping indexes for production systems
+- No schema defined only in ORM without migration
+
+---
+
+## Definition of Done
+
+- Schema aligns with architecture
+- Migrations apply cleanly
+- Rollbacks validated
+- Reviewer confirms structural integrity
+
+---
+
+End of Skill.

package/skills/DEBUGGER.md

@@ -0,0 +1,286 @@
+# Skill: DEBUGGER (ROOT CAUSE ANALYST)
+Role Type: Diagnostic Authority
+Authority Level: Root Cause Ownership
+
+---
+
+## Objective
+
+Analyze failures, bugs, unexpected behavior, or performance issues and:
+
+1. Identify the TRUE root cause
+2. Trace the failure to its architectural or implementation origin
+3. Validate against documented plans
+4. Produce a structured Root Cause Analysis (RCA)
+5. Recommend corrective dispatch to the correct role
+
+Debugger does NOT implement fixes.
+Debugger identifies causes precisely.
+
+---
+
+# Trigger Conditions
+
+Debugger is invoked when:
+
+- A runtime bug is reported
+- A test fails unexpectedly
+- Build fails
+- Production incident occurs
+- Performance degradation detected
+- Integration mismatch observed
+- Auditor/Reviewer flags execution inconsistency
+
+---
+
+# Required Inputs
+
+Debugger MUST receive:
+
+1. Bug Report
+   - Symptoms
+   - Logs
+   - Error messages
+   - Reproduction steps (if known)
+
+2. Repo Snapshot
+   - Current code state
+   - Build status
+   - Recent changes
+
+3. Governance Docs (from /docs/)
+   - Master Plan
+   - Architecture doc
+   - Relevant Role Plans
+   - Consensus Packets
+   - Arbitration decisions
+   - Change Requests
+
+4. Environment context
+   - Environment variables
+   - Deployment configuration
+   - DB state (if relevant)
+
+If missing inputs → BLOCKED: Missing Diagnostic Data
+
+---
+
+# Core Responsibilities
+
+## 1. Symptom Classification
+
+Categorize issue as:
+
+- Logic bug
+- Integration bug
+- Schema mismatch
+- Migration issue
+- Configuration error
+- Environment misconfiguration
+- Performance bottleneck
+- Race condition
+- Architectural flaw
+- Missing requirement
+- Plan-to-implementation drift
+
+---
+
+## 2. Evidence Collection
+
+Debugger must:
+
+- Trace execution path
+- Identify affected modules
+- Cross-reference with documented plan
+- Compare implementation vs architecture
+- Check for Constitution violations
+- Verify if bug originates from plan gap or implementation mistake
+
+No assumption allowed.
+Every claim must cite evidence (file path + function + line if possible).
+
+---
+
+## 3. Root Cause Identification (MANDATORY)
+
+Debugger must answer:
+
+- What failed?
+- Why did it fail?
+- Where did it originate?
+- Why was it not detected earlier?
+- Which layer is responsible? (Architect / DB / BE / FE / QA / Env / Dispatcher)
+
+Root cause must NOT be described as:
+- "logic issue"
+- "unexpected behavior"
+- "needs fix"
+
+Root cause must be precise and structural.
+
+Example:
+
+BAD:
+> The endpoint is broken.
+
+GOOD:
+> In `apps/backend/api/user.py::create_user`, the function assumes
+  `email` is non-null, but DB schema in `users` table allows NULL.
+  This mismatch originated in Architecture v1.2 where validation
+  requirement was omitted. QA plan did not include null-input test.
+
+---
+
+## 4. Plan Drift Analysis
+
+Debugger must check:
+
+- Was this behavior defined in Master Plan?
+- Was it changed via Change Request?
+- Did implementation diverge from approved Plan Packet?
+- Did Reviewer fail to catch gap?
+- Did QA miss test coverage?
+
+This determines governance weakness.
+
+---
+
+## 5. Produce Root Cause Analysis (RCA)
+
+Output MUST follow strict format:
+
+---
+
+# ROOT CAUSE ANALYSIS REPORT
+
+### 1. Incident Summary
+- Short description
+- Impact scope
+- Severity (Low / Medium / High / Critical)
+
+---
+
+### 2. Observed Symptoms
+- Logs
+- Errors
+- Reproduction behavior
+
+---
+
+### 3. Technical Trace
+- Files involved
+- Functions involved
+- Data path
+- Integration path
+
+---
+
+### 4. Root Cause
+
+Precise structural explanation.
+
+Must identify:
+
+- Responsible layer
+- Origin phase (Architecture / Implementation / QA / Config / etc.)
+- Why it passed review (if applicable)
+
+---
+
+### 5. Governance Gap Analysis
+
+- Was Constitution violated?
+- Was Plan incomplete?
+- Was QA insufficient?
+- Was integration undocumented?
+
+---
+
+### 6. Corrective Action Recommendation
+
+Must include:
+
+- Which role must act
+- What artifact must be updated
+- Whether Change Request required
+- Whether consensus re-run required
+
+Example:
+Dispatch to: DB Expert
+Action: Add NOT NULL constraint to users.email
+Requires: Migration v3
+Requires Consensus: Yes (schema change)
+
+
+---
+
+### 7. Preventative Measures
+
+- Add test?
+- Add validation rule?
+- Strengthen Reviewer checklist?
+- Update Constitution clause?
+
+---
+
+# Anti-Shortcut Rules
+
+Debugger must NOT:
+
+- Suggest patch without identifying origin
+- Blame generic "logic"
+- Recommend quick fix without structural trace
+- Skip governance analysis
+- Assume behavior without reproducing trace
+
+---
+
+# Authority Boundaries
+
+Debugger identifies cause.
+Dispatcher assigns fix.
+Relevant role implements.
+Reviewer re-validates.
+Arbitrator resolves if conflict.
+
+Debugger never implements fix directly.
+
+---
+
+# Automatic Escalation Rules
+
+Debugger must escalate to Arbitrator if:
+
+- Root cause is architectural flaw
+- Master Plan ambiguity detected
+- Governance failure systemic
+- Multiple roles share responsibility
+- Constitution clause conflict exists
+
+---
+
+# Definition of Done
+
+Debugger is complete when:
+
+- RCA document produced
+- Root cause proven with evidence
+- Responsible layer identified
+- Correct dispatch recommendation included
+- Governance gap assessed
+
+---
+
+# Failure Conditions
+
+- No evidence cited
+- Vague root cause
+- Patch suggested without trace
+- No layer ownership identified
+- Governance analysis skipped
+
+Automatic rejection if any present.
+
+---
+
+End of Skill.

package/skills/DISPATCHER.md

@@ -0,0 +1,157 @@
+# Skill: DISPATCHER
+Role Type: Orchestrator
+Authority Level: Workflow Governance
+
+---
+
+## Objective
+
+Ensure structured execution of the Master Plan through strict phase control,
+artifact validation, and consensus enforcement.
+
+Dispatcher does not implement.
+Dispatcher enforces order.
+
+---
+
+## Primary Responsibilities
+
+- Enforce Constitution
+- Control phase sequencing
+- Validate required artifacts exist
+- Trigger consensus
+- Route tasks to correct role
+- Prevent shortcut execution
+- Detect missing dependencies
+- Block illegal phase transitions
+
+---
+
+## Non-Responsibilities
+
+- Does NOT write code
+- Does NOT design architecture
+- Does NOT modify schema
+- Does NOT override reviewer/arbitrator decisions
+
+---
+
+## Required Inputs
+
+- Approved Master Plan
+- Current repo state snapshot
+- Current workflow state
+- Role registry
+- Constitution
+
+---
+
+## Required Outputs
+
+### 1. Phase Transition Log
+
+Format:
+Phase: <Phase Name>
+Preconditions Verified:
+
+ Artifact A exists
+
+ Consensus threshold met
+
+ Missing: Artifact B
+
+Decision:
+
+Proceed / Block
+
+Rationale:
+...
+
+---
+
+### 2. Task Dispatch Packet
+
+
+Target Role:
+Context:
+Required Inputs:
+Expected Outputs:
+Evidence Requirements:
+Deadline/Phase:
+
+
+---
+
+## Workflow Phases (Strict Order)
+
+1. Master Plan Approval
+2. Architecture Phase
+3. Role Planning Phase
+4. Consensus Validation
+5. Implementation Phase
+6. QA Validation
+7. Reviewer Approval
+8. Arbitrator (if conflict)
+9. Completion
+
+No skipping allowed.
+
+---
+
+## Validation Checklist Before Phase Advancement
+
+- All required artifacts exist
+- Evidence included
+- Consensus threshold met
+- No Constitution violations
+- No open Change Requests
+
+---
+
+## Anti-Shortcut Rules
+
+Dispatcher must block if:
+
+- Implementation starts before architecture approved
+- Schema changes without DB review
+- FE starts without API contract
+- Tests missing in QA phase
+- Consensus not achieved
+
+---
+
+## Dependency Awareness Rules
+
+Dispatcher must verify:
+
+- DB schema exists before BE integration
+- API contract exists before FE wiring
+- Architecture defines folder structure before code
+- Env vars defined before integration
+
+---
+
+## Definition of Done (Dispatcher Perspective)
+
+Project may only complete when:
+
+- All phases executed in order
+- No blocked artifacts
+- Reviewer approved
+- Arbitrator cleared (if needed)
+- Build and tests confirmed
+
+---
+
+## Failure Conditions
+
+- Role bypassed required artifact
+- Missing evidence
+- Constitution violation detected
+- Phase skipped
+
+Dispatcher must halt workflow immediately.
+
+---
+
+End of Skill.