popeye-cli 1.9.5 → 2.0.0

package/skills/JOURNALIST.md

@@ -0,0 +1,247 @@
+# Skill: JOURNALIST (PROJECT RECORDER)
+Role Type: Governance Recorder
+Authority Level: Immutable Documentation Authority
+
+---
+
+## Objective
+
+Ensure that every approved Plan Packet and Consensus Packet is:
+
+- Persisted under /docs/
+- Versioned
+- Immutable
+- Traceable
+- Linked to Master Plan
+- Cross-referenced for future audits
+
+Journalist does NOT influence decisions.
+Journalist ensures history cannot be rewritten.
+
+---
+
+## Primary Responsibilities
+
+- Record approved Plan Packets
+- Record Consensus Packets
+- Record Arbitrator decisions
+- Maintain version history
+- Maintain decision index
+- Maintain changelog timeline
+- Detect missing documentation
+- Prevent silent edits
+
+---
+
+## Non-Responsibilities
+
+- Does NOT modify plans
+- Does NOT participate in consensus
+- Does NOT interpret scope
+- Does NOT alter artifacts
+- Does NOT summarize differently than source
+
+Journalist records. It does not reinterpret.
+
+---
+
+## Trigger Conditions
+
+Journalist is triggered ONLY when:
+
+- Consensus final_status = APPROVED
+- OR final_status = APPROVED_WITH_PATCH
+- OR final_status = REJECTED
+- OR final_status = REVISION_REQUIRED
+
+No packet is allowed to disappear.
+
+---
+
+## Required Inputs
+
+1. Final Plan Packet (approved version)
+2. Consensus Packet
+3. Arbitrator Result (if exists)
+4. Dispatcher Phase Context
+5. Timestamp
+6. Version number
+
+If any missing → BLOCKED: Missing Inputs
+
+---
+
+## Documentation Structure (Mandatory)
+
+All logs must be written under:
+/docs/
+├── master-plan/
+├── architecture/
+├── role-plans/
+├── consensus/
+├── arbitration/
+├── revisions/
+├── completion/
+└── INDEX.md
+
+
+---
+
+## File Naming Convention
+
+Format:
+
+
+<phase>_<packet-id>v<version><timestamp>.md
+
+
+Example:
+
+
+architecture_2f8a_v1_2026-02-20.md
+consensus_2f8a_v1_2026-02-20.md
+
+
+No overwriting allowed.
+Each version creates a new file.
+
+---
+
+## Required Document Content Structure
+
+Every recorded document must contain:
+
+### 1. Header Metadata
+
+- Project Name
+- Packet ID
+- Version
+- Phase
+- Timestamp
+- Dispatcher reference
+- Constitution version
+
+---
+
+### 2. Master Plan Reference
+
+- Master Plan version
+- Scope summary
+- Change Requests (if any)
+
+---
+
+### 3. Plan Content (verbatim)
+
+Must include full approved Plan Packet content.
+No summarization.
+No omission.
+
+---
+
+### 4. Consensus Summary
+
+- Reviewer verdicts
+- Approval percentage
+- Blocking issues (resolved or not)
+- Hallucination flags
+- Constitution violations (if any)
+
+---
+
+### 5. Arbitrator Decision (if applicable)
+
+- Converged patch
+- Final verdict
+- Rationale
+- Dispatcher next step
+
+---
+
+### 6. Execution Traceability Section
+
+Must include:
+
+- Which artifacts are now authorized
+- Which roles are unblocked
+- Which phase is next
+- Hash or fingerprint (optional but recommended)
+
+---
+
+## INDEX.md Maintenance Rules
+
+Journalist must maintain:
+
+- Chronological list of all packets
+- Phase grouping
+- Quick link to latest approved version per phase
+- Revision count per artifact
+
+Format example:
+
+Project Governance Index
+Architecture
+
+v1 - APPROVED - 2026-02-20 - Packet 2f8a
+
+v2 - APPROVED_WITH_PATCH - 2026-02-21 - Packet 5c91
+
+Role Planning
+
+v1 - REJECTED - 2026-02-22 - Packet 8a12
+
+
+INDEX must never be deleted or rewritten.
+
+---
+
+## Anti-Tampering Rules
+
+Journalist must detect and flag:
+
+- Attempt to overwrite existing file
+- Missing version increment
+- Missing consensus packet
+- Inconsistent packet reference
+- Timestamp anomalies
+
+If detected → BLOCKED and notify Dispatcher.
+
+---
+
+## Immutability Principle
+
+Once written:
+- Documents are read-only
+- Edits require new version
+- Historical record remains untouched
+
+---
+
+## Definition of Done
+
+Journalist is complete when:
+
+- Plan Packet is stored
+- Consensus Packet is stored
+- Arbitrator decision stored (if applicable)
+- INDEX.md updated
+- Documentation structure validated
+- No overwrites occurred
+
+---
+
+## Failure Conditions
+
+- Missing Plan Packet
+- Missing Consensus Packet
+- Version conflict
+- Overwrite attempt
+- Inconsistent metadata
+
+Automatic block if any occur.
+
+---
+
+End of Skill.

package/skills/MARKETING_EXPERT.md

@@ -0,0 +1,23 @@
+# Skill: MARKETING EXPERT
+Role Type: Positioning Authority
+
+---
+
+## Objective
+
+Ensure product messaging aligns with value proposition.
+
+---
+
+## Responsibilities
+
+- ICP definition
+- Messaging clarity
+- Pricing logic
+- Conversion strategy
+- Funnel alignment
+
+---
+
+Definition of Done:
+Clear, differentiated positioning aligned with product reality.

package/skills/PHASE_GATE_ENGINE_SPEC.md

@@ -0,0 +1,171 @@
+# PHASE GATE ENGINE SPEC
+
+Defines the deterministic workflow engine of Popeye.
+
+Version: 1.1 (Autonomy Hardening Gap Fixes)
+
+---
+
+## States
+
+INTAKE
+CONSENSUS_MASTER_PLAN
+ARCHITECTURE
+CONSENSUS_ARCHITECTURE
+ROLE_PLANNING
+CONSENSUS_ROLE_PLANS
+IMPLEMENTATION
+QA_VALIDATION
+REVIEW
+AUDIT
+PRODUCTION_GATE
+RECOVERY_LOOP (conditional)
+DONE
+STUCK (safety valve)
+
+---
+
+## Gate Rules
+
+Each state defines:
+
+- Required Artifacts
+- Required Build/Test Commands
+- Required Consensus Status (threshold for consensus phases)
+- Allowed Transitions
+- Fail Transition (always RECOVERY_LOOP, except terminal phases)
+
+No state skipping allowed.
+
+---
+
+## Gate Evaluation (v1.1)
+
+Before evaluating any gate, the orchestrator performs:
+
+1. **Constitution Verification** - verifies `skills/POPEYE_CONSTITUTION.md` hash matches the stored hash from pipeline start. If the constitution has been modified, the gate is blocked.
+
+2. **Gate Evaluation** - checks required artifacts, check results, and consensus thresholds. The `evaluateGate()` function accepts optional `constitutionValid` and `constitutionReason` options.
+
+3. **Gate Result Merge** - preserves `score`/`consensusScore` values from consensus phase handlers while updating `pass`/`blockers` from the gate engine. This prevents consensus scores from being overwritten.
+
+## GateResult Interface
+
+```typescript
+interface GateResult {
+  phase: PipelinePhase;
+  pass: boolean;
+  score?: number;           // Consensus score from phase handler (preserved by merge)
+  blockers: string[];
+  missingArtifacts: ArtifactType[];
+  failedChecks: GateCheckType[];
+  consensusScore?: number;  // Alternative consensus score field (preserved by merge)
+  timestamp: string;
+}
+```
+
+---
+
+## Change Request Routing (v1.1)
+
+After REVIEW and AUDIT phases pass their gates, the orchestrator checks `pipeline.pendingChangeRequests` for any CRs with `status: 'proposed'`. If found, the pipeline routes to the CR's `target_phase` instead of continuing normal progression.
+
+### CR Routing Map
+
+| Change Type   | Target Phase             |
+|---------------|--------------------------|
+| scope         | CONSENSUS_MASTER_PLAN    |
+| architecture  | CONSENSUS_ARCHITECTURE   |
+| dependency    | CONSENSUS_ROLE_PLANS     |
+| config        | QA_VALIDATION            |
+| requirement   | CONSENSUS_MASTER_PLAN    |
+
+### CR Lifecycle
+
+```
+proposed  ->  approved (routed by orchestrator)
+          ->  rejected
+```
+
+### CR Sources
+
+- **REVIEW phase**: Creates CRs when implementation drift is detected (config changes, large line deltas)
+- **AUDIT phase**: Creates CRs for blocking architectural findings and security issues
+
+---
+
+## Recovery Loop
+
+If any gate FAILS:
+
+1. Enter RECOVERY_LOOP
+2. Trigger Debugger for RCA
+3. Produce RCA Packet (JSON artifact with `requires_phase_rewind_to` field)
+4. Dispatcher generates Recovery Plan
+5. Consensus on Recovery Plan
+6. Implement fixes
+7. On RECOVERY_LOOP success:
+   - If RCA specifies `requires_phase_rewind_to`, rewind to that phase
+   - Otherwise, re-run the originally failed phase
+8. Max 5 iterations before STUCK
+
+### RCA Rewind (v1.1)
+
+After RECOVERY_LOOP succeeds, the orchestrator reads the latest RCA JSON artifact from disk and parses `requires_phase_rewind_to`. This enables root-cause-aware recovery:
+
+- Implementation failure caused by architecture gap: rewind to ARCHITECTURE
+- QA failure caused by missing role plan: rewind to ROLE_PLANNING
+- If no rewind target or no RCA found: return to the originally failed phase
+
+---
+
+## Termination Conditions
+
+- Production Gate PASS -> DONE
+- Max Recovery Reached -> STUCK REPORT
+
+---
+
+## Stuck Report Must Include
+
+- Current failure
+- Root cause summary
+- Failed iterations count
+- Required human input
+
+---
+
+## State Transition Example
+
+ARCHITECTURE -> allowed only if:
+- Architecture Plan exists
+- Repo snapshot exists
+- Constitution integrity verified (v1.1)
+- No blocking issues
+
+IMPLEMENTATION -> allowed only if:
+- Role Plans approved (consensus threshold met)
+- Constitution integrity verified (v1.1)
+- No pending change requests (v1.1)
+
+REVIEW -> AUDIT (or CR target) after:
+- Review decision artifact exists
+- Repo snapshot exists
+- Constitution integrity verified (v1.1)
+- If pending CRs exist -> route to CR target phase (v1.1)
+- If no pending CRs -> normal progression to AUDIT
+
+---
+
+## Pipeline State Schema (v1.1 additions)
+
+```typescript
+pendingChangeRequests?: Array<{
+  cr_id: string;
+  change_type: 'scope' | 'architecture' | 'dependency' | 'config' | 'requirement';
+  target_phase: PipelinePhase;
+  status: 'proposed' | 'approved' | 'rejected';
+}>;
+
+failedPhase?: PipelinePhase;  // Tracks which phase failed for recovery routing
+```

package/skills/PLAN_PACKET_SCHEMA.md

@@ -0,0 +1,222 @@
+# PLAN PACKET SCHEMA
+Version: 1.0
+Purpose: Standardized artifact required for Reviewer and Arbitrator evaluation.
+
+This schema defines the exact structure of a Plan Packet that must be submitted
+for consensus review.
+
+No Reviewer may operate without a valid Plan Packet.
+
+---
+
+# 1. Required Top-Level Fields
+
+A valid Plan Packet MUST contain:
+
+1. metadata
+2. master_plan_reference
+3. current_phase
+4. repo_snapshot
+5. constraints
+6. constitution_reference
+7. proposed_plan
+8. acceptance_criteria
+9. artifact_dependencies
+
+If any field is missing → BLOCKED: Missing Inputs
+
+---
+
+# 2. Field Definitions
+
+## 2.1 metadata
+
+Required:
+
+- project_name
+- packet_id (UUID)
+- version
+- timestamp
+- author_role (Dispatcher/Popeye)
+- target_phase
+
+Example:
+metadata:
+project_name: popeye-cli
+packet_id: 2f8a...
+version: 1.3
+timestamp: 2026-02-20T12:45:00Z
+author_role: Dispatcher
+target_phase: Architecture
+
+
+---
+
+## 2.2 master_plan_reference
+
+Must include:
+
+- master_plan_version
+- summary_of_scope
+- explicit link/path to stored master plan artifact
+
+Must confirm:
+- No scope drift
+- No unapproved changes
+
+---
+
+## 2.3 current_phase
+
+One of:
+
+- MasterPlan
+- Architecture
+- RolePlanning
+- Consensus
+- Implementation
+- QA
+- Review
+- Arbitration
+- Completion
+
+---
+
+## 2.4 repo_snapshot
+
+Must include:
+
+- existing folders
+- key files
+- declared tech stack
+- declared dependencies
+- env vars currently defined
+- database state (if exists)
+- build status (if known)
+
+Must not hallucinate files.
+Must reflect actual filesystem.
+
+---
+
+## 2.5 constraints
+
+Include:
+
+- Language(s)
+- Framework(s)
+- Hosting constraints
+- Performance requirements
+- Security constraints
+- Backward compatibility requirements
+- Regulatory constraints (if any)
+
+---
+
+## 2.6 constitution_reference
+
+Must confirm:
+
+- Constitution version used
+- No violations detected prior to review
+
+---
+
+## 2.7 proposed_plan
+
+This is the artifact under review.
+
+Must include:
+
+- Clear phase breakdown
+- Role ownership per task
+- Explicit artifact outputs
+- Integration wiring steps
+- Risk handling
+- Testing plan references
+- Build validation steps
+
+Proposed plan MUST be deterministic.
+No vague phrases allowed:
+- "handle errors"
+- "add tests"
+- "connect later"
+- "implement logic"
+
+Everything must specify what, where, and how.
+
+---
+
+## 2.8 acceptance_criteria
+
+Must list:
+
+- Functional requirements
+- Non-functional requirements
+- Integration requirements
+- Test pass conditions
+- Build pass condition
+- Deployment criteria (if relevant)
+
+---
+
+## 2.9 artifact_dependencies
+
+Explicit dependency mapping:
+
+Example:
+
+- Architecture → required before BE
+- DB Schema → required before BE
+- API Contract → required before FE
+- QA Plan → required before Implementation
+- Review Approval → required before Completion
+
+Missing dependency mapping → automatic rejection.
+
+---
+
+# 3. Plan Packet Validation Rules
+
+A Plan Packet is INVALID if:
+
+- It references files not present in repo_snapshot
+- It introduces schema changes without DB ownership
+- It begins implementation before architecture approval
+- It omits test strategy
+- It lacks integration wiring steps
+- It includes placeholders or mocks without explicit approval
+
+---
+
+# 4. Hallucination Detection Rule
+
+If proposed_plan references:
+
+- Non-existent modules
+- Non-existent env vars
+- Undefined API routes
+- Undefined DB tables
+- Undefined services
+
+Reviewer must flag as Hallucination.
+
+---
+
+# 5. Determinism Requirement
+
+Plan must be executable step-by-step.
+
+If two different engineers could interpret steps differently → it fails determinism.
+
+---
+
+# 6. Versioning
+
+Every Plan Packet must increment version if modified.
+
+No silent edits allowed.
+
+---
+
+End of Schema.