moai-adk 0.9.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

moai_adk/templates/.moai/memory/gitflow-protection-policy.md

@@ -1,330 +0,0 @@
-# GitFlow Protection Policy
-
-**Document ID**: @DOC:GITFLOW-POLICY-ALIAS
-**Published**: 2025-10-17
-**Updated**: 2025-10-29
-**Status**: **Enforced via GitHub Branch Protection** (v0.8.3+)
-**Scope**: Personal and Team modes
-
----
-
-## Overview
-
-MoAI-ADK **enforces** a GitFlow-inspired workflow through GitHub Branch Protection. As of v0.8.3, the `main` branch is protected and requires Pull Requests for all changes, including from administrators.
-
-**What Changed**: Previously (v0.3.5-v0.8.2), we used an advisory approach with warnings. Now we enforce proper GitFlow to ensure code quality and prevent accidental direct pushes to main.
-
-## Key Requirements (Enforced)
-
-### 1. Main Branch Access (Enforced)
-
-| Requirement | Summary | Enforcement |
-|-------------|---------|-------------|
-| **Merge via develop** | MUST merge `develop` into `main` | ✅ Enforced |
-| **Feature branches off develop** | MUST branch from `develop` and raise PRs back to `develop` | ✅ Enforced |
-| **Release process** | Release flow: `develop` → `main` (PR required) | ✅ Enforced |
-| **Force push** | Blocked on `main` | ✅ Blocked |
-| **Direct push** | Blocked on `main` (PR required) | ✅ Blocked |
-
-### 2. Git Workflow (Required)
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                ENFORCED GITFLOW                         │
-│         (GitHub Branch Protection Active)               │
-└─────────────────────────────────────────────────────────┘
-
-        develop (required base branch)
-          ↑     ↓
-    ┌─────────────────┐
-    │                 │
-    │   developer work │
-    │                 │
-    ↓                 ↑
-feature/SPEC-{ID}   [PR: feature -> develop]
-                     [code review + approval]
-                     [Merge to develop]
-
-    develop (stable)
-         ↓
-         │   (release manager prepares)
-         ↓
-    [PR: develop -> main]
-    [Code review + approval REQUIRED]
-    [All discussions resolved]
-    [CI/CD validation]
-    [tag creation]
-         ↓
-       main (protected release)
-```
-
-**Enforcement**: Direct pushes to `main` are **blocked** via GitHub Branch Protection. All changes must go through Pull Requests.
-
-## Technical Implementation
-
-### Pre-push Hook (Advisory Mode)
-
-**Location**: `.git/hooks/pre-push`  
-**Purpose**: Warn on `main` branch pushes without blocking them
-
-```bash
-# When attempting to push to main:
-⚠️  ADVISORY: Non-standard GitFlow detected
-
-Current branch: feature/SPEC-123
-Target branch: main
-
-Recommended GitFlow workflow:
-  1. Work on feature/SPEC-{ID} branch (created from develop)
-  2. Push to feature/SPEC-{ID} and create PR to develop
-  3. Merge into develop after code review
-  4. When develop is stable, create PR from develop to main
-  5. Release manager merges develop -> main with tag
-
-✓ Push will proceed (flexibility mode enabled)
-```
-
-### Force Push Advisory
-
-```bash
-⚠️  ADVISORY: Force-push to main branch detected
-
-Recommended approach:
-  - Use GitHub PR with proper code review
-  - Ensure changes are merged via fast-forward
-
-✓ Push will proceed (flexibility mode enabled)
-```
-
----
-
-## Workflow Examples
-
-### Scenario 1: Standard Feature Development (Recommended)
-
-```bash
-# 1. Sync latest code from develop
-git checkout develop
-git pull origin develop
-
-# 2. Create a feature branch (from develop)
-git checkout -b feature/SPEC-001-new-feature
-
-# 3. Implement the change
-# ... write code and tests ...
-
-# 4. Commit
-git add .
-git commit -m "..."
-
-# 5. Push
-git push origin feature/SPEC-001-new-feature
-
-# 6. Open a PR: feature/SPEC-001-new-feature -> develop
-
-# 7. Merge into develop after review and approval
-```
-
-### Scenario 2: Fast Hotfix (Flexible)
-
-```bash
-# When an urgent fix is required:
-
-# Option 1: Recommended (via develop)
-git checkout develop
-git checkout -b hotfix/critical-bug
-# ... apply fix ...
-git push origin hotfix/critical-bug
-# Open PRs: hotfix -> develop -> main
-
-# Option 2: Direct fix on main (allowed, not recommended)
-git checkout main
-# ... apply fix ...
-git commit -m "Fix critical bug"
-git push origin main  # ⚠️ Advisory warning appears but push continues
-```
-
-### Scenario 3: Release (Standard or Flexible)
-
-```bash
-# Standard approach (recommended):
-git checkout develop
-gh pr create --base main --head develop --title "Release v1.0.0"
-
-# Direct push (allowed):
-git checkout develop
-git push origin main  # ⚠️ Advisory warning appears but push continues
-git tag -a v1.0.0 -m "Release v1.0.0"
-git push origin v1.0.0
-```
-
----
-
-## Policy Modes
-
-### Strict Mode (Active, v0.8.3+) ✅ ENFORCED
-
-**GitHub Branch Protection Enabled**:
-- ✅ **enforce_admins: true** - Administrators must follow all rules
-- ✅ **required_pull_request_reviews** - 1 approval required
-- ✅ **required_conversation_resolution** - All discussions must be resolved
-- ✅ **Block direct pushes to `main`** - PR required for all users
-- ✅ **Block force pushes** - Prevents history rewriting
-- ✅ **Block branch deletion** - Protects main from accidental deletion
-
-**What This Means**:
-- ❌ No one (including admins) can push directly to `main`
-- ✅ All changes must go through Pull Requests
-- ✅ PRs require code review approval
-- ✅ All code discussions must be resolved before merge
-- ✅ Enforces proper GitFlow: feature → develop → main
-
-### Advisory Mode (Legacy, v0.3.5 - v0.8.2)
-
-- ⚠️ Warned but allowed direct pushes to `main`
-- ⚠️ Warned but allowed force pushes
-- ⚠️ Recommended best practices while preserving flexibility
-- ❌ **Deprecated** - Replaced by Strict Mode for better quality control
-
----
-
-## Recommended Checklist
-
-Every contributor should ensure:
-
-- [ ] `.git/hooks/pre-push` exists and is executable (755)
-- [ ] Feature branches fork from `develop`
-- [ ] Pull requests target `develop`
-- [ ] Releases merge `develop` → `main`
-
-**Verification Commands**:
-```bash
-ls -la .git/hooks/pre-push
-git branch -vv
-```
-
----
-
-## FAQ
-
-**Q: Can we merge into `main` from branches other than `develop`?**  
-A: Yes. You will see an advisory warning, but the merge proceeds. The recommended path remains `develop` → `main`.
-
-**Q: Are force pushes allowed?**  
-A: Yes. You receive a warning, but the push succeeds. Use with caution.
-
-**Q: Can we commit/push directly to `main`?**  
-A: Yes. Expect an advisory warning, yet the push continues.
-
-**Q: Can I disable the hook entirely?**  
-A: Yes. Remove `.git/hooks/pre-push` or strip its execute permission.
-
-**Q: Why switch to Advisory Mode?**
-A: Advisory Mode was used in v0.3.5-v0.8.2. As of v0.8.3, we've switched to Strict Mode with GitHub Branch Protection for better quality control.
-
-**Q: What if develop falls behind main?**
-A: This can happen when hotfixes or releases go directly to main. Regularly sync main → develop to prevent divergence. See "Maintaining develop-main Sync" section below.
-
-**Q: Can I bypass branch protection in emergencies?**
-A: No. Even administrators must follow the PR process. For true emergencies, temporarily disable protection via GitHub Settings (requires admin access), but re-enable immediately after.
-
----
-
-## Maintaining develop-main Sync
-
-### ⚠️ Critical Rule: develop Must Stay Current
-
-**Problem**: When main receives direct commits (hotfixes, emergency releases) without syncing back to develop, GitFlow breaks:
-
-```
-❌ BAD STATE:
-develop: 3 commits ahead, 29 commits behind main
-- develop has outdated dependencies
-- New features branch from old code
-- Merge conflicts multiply over time
-```
-
-### Signs of Drift
-
-Monitor for these warnings:
-- `git status` shows "Your branch is X commits behind main"
-- Feature branches conflict with main during PR
-- CI/CD failures due to dependency mismatches
-- Version numbers in develop don't match main
-
-### Recovery Procedure
-
-When develop falls behind main:
-
-1. **Assess the Gap**
-   ```bash
-   git log --oneline develop..main  # Commits in main but not develop
-   git log --oneline main..develop  # Commits in develop but not main
-   ```
-
-2. **Sync Strategy: Merge main into develop (Recommended)**
-   ```bash
-   git checkout develop
-   git pull origin develop        # Get latest develop
-   git merge main                 # Merge main into develop
-   # Resolve conflicts if any (prefer main for version/config files)
-   git push origin develop
-   ```
-
-3. **Emergency Only: Reset develop to main (Destructive)**
-   ```bash
-   # ⚠️ ONLY if develop's unique commits are unwanted
-   git checkout develop
-   git reset --hard main
-   git push origin develop --force
-   ```
-
-### Prevention: Regular Sync Schedule
-
-**After every main release** (REQUIRED):
-```bash
-# Immediately after merging develop → main:
-git checkout develop
-git merge main
-git push origin develop
-```
-
-**Weekly maintenance** (for active projects):
-```bash
-# Every Monday morning:
-git checkout develop
-git pull origin main
-git push origin develop
-```
-
-### Real-World Case Study (2025-10-29)
-
-**Situation**: develop was 29 commits behind main due to:
-- v0.8.2, v0.8.3 released directly to main
-- No reverse sync to develop
-- Feature branches contained outdated code
-
-**Resolution**:
-- Merged main → develop (14 file conflicts)
-- Resolved conflicts prioritizing main's versions
-- TAG validation bypassed for merge commit
-- Enabled Strict Mode to prevent future direct pushes
-
-**Lesson**: With Strict Mode active, this won't happen again. All releases must go through develop → main PR flow.
-
----
-
-## Policy Change Log
-
-| Date       | Change                                           | Owner        |
-|------|------|--------|
-| 2025-10-17 | Initial policy drafted (Strict Mode)             | git-manager  |
-| 2025-10-17 | Switched to Advisory Mode (warnings only)        | git-manager  |
-| 2025-10-29 | **Enabled GitHub Branch Protection (Strict Mode)** | Alfred       |
-| 2025-10-29 | Added develop-main sync guidelines and real-world case study | Alfred       |
-| 2025-10-29 | Enforced `enforce_admins`, `required_conversation_resolution` | Alfred       |
-
----
-
-**This policy is advisory—adapt it to fit your project needs.**  
-**Reach out to the team lead or release engineer for questions or suggestions.**

moai_adk/templates/.moai/project/product.md

@@ -1,161 +0,0 @@
----
-id: PRODUCT-001
-version: 0.1.3
-status: active
-created: 2025-10-01
-updated: 2025-10-17
-author: @project-owner
-priority: high
----
-
-# {{PROJECT_NAME}} Product Definition
-
-## HISTORY
-
-### v0.1.3 (2025-10-17)
-- **UPDATED**: Template version synced (v0.3.8)
-- **AUTHOR**: @Alfred
-- **SECTIONS**: Mission (finalized team of 12 agents: Alfred + 11 specialists)
-  - Added implementation-planner, tdd-implementer, quality-gate
-  - Split code-builder into implementation-planner + tdd-implementer + quality-gate
-
-### v0.1.2 (2025-10-17)
-- **UPDATED**: Agent count adjusted (9 → 11)
-- **AUTHOR**: @Alfred
-- **SECTIONS**: Mission (updated Alfred SuperAgent roster)
-
-### v0.1.1 (2025-10-17)
-- **UPDATED**: Template defaults aligned with the real MoAI-ADK project
-- **AUTHOR**: @Alfred
-- **SECTIONS**: Mission, User, Problem, Strategy, Success populated with project context
-
-### v0.1.0 (2025-10-01)
-- **INITIAL**: Authored the product definition document
-- **AUTHOR**: @project-owner
-- **SECTIONS**: Mission, User, Problem, Strategy, Success, Legacy
-
----
-
-## @DOC:MISSION-001 Core Mission
-
-> **"No SPEC, no CODE."**
-
-{{PROJECT_NAME}} combats Frankenstein code at the root by enforcing a **SPEC-first TDD methodology**.
-
-### Core Value Proposition
-
-#### Four Key Values
-
-1. **Consistency**: A three-step SPEC → TDD → Sync pipeline safeguards delivery quality.
-2. **Quality**: TRUST principles (Test First, Readable, Unified, Secured, Trackable) apply automatically.
-3. **Traceability**: The @TAG system (`@SPEC → @TEST → @CODE → @DOC`) preserves end-to-end lineage.
-4. **Universality**: Supports diverse programming languages and frameworks.
-
-#### Alfred SuperAgent
-
-**Alfred** coordinates a team of 12 AI agents (Alfred + 11 specialists):
-- **spec-builder** 🏗️: Authors SPECs (EARS pattern) – Sonnet
-- **implementation-planner** 📋: Analyzes SPECs and derives implementation plans – Sonnet
-- **tdd-implementer** 🔬: Executes RED–GREEN–REFACTOR cycles – Sonnet
-- **quality-gate** 🛡️: Enforces TRUST principles – Haiku
-- **doc-syncer** 📖: Maintains living documentation – Haiku
-- **tag-agent** 🏷️: Manages the TAG system – Haiku
-- **git-manager** 🚀: Automates Git workflows – Haiku
-- **debug-helper** 🔍: Diagnoses runtime issues – Sonnet
-- **trust-checker** ✅: Verifies TRUST compliance – Haiku
-- **cc-manager** 🛠️: Configures Claude Code – Sonnet
-- **project-manager** 📂: Bootstraps projects – Sonnet
-
-## @SPEC:USER-001 Primary Users
-
-### Primary Audience
-- **Who**: [Describe your main user segment]
-- **Core Needs**: [Explain the problems they want solved]
-- **Critical Scenarios**: [Outline their primary usage scenarios]
-
-### Secondary Audience (Optional)
-- **Who**: [Describe any secondary user group]
-- **Needs**: [Capture their requirements]
-
-## @SPEC:PROBLEM-001 Problems to Solve
-
-### High Priority
-1. [Top problem to resolve]
-2. [Second critical problem]
-3. [Third critical problem]
-
-### Medium Priority
-- [Problems with moderate urgency]
-
-### Current Failure Cases
-- [Limitations or failure patterns in existing solutions]
-
-## @DOC:STRATEGY-001 Differentiators & Strengths
-
-### Strengths Versus Alternatives
-1. [Primary differentiator]
-   - **When it matters**: [Scenario where the strength shines]
-
-2. [Second differentiator]
-   - **When it matters**: [Concrete usage example]
-
-## @SPEC:SUCCESS-001 Success Metrics
-
-### Immediately Measurable KPIs
-1. [Metric 1]
-   - **Baseline**: [Target value and measurement approach]
-
-2. [Metric 2]
-   - **Baseline**: [Target value and measurement approach]
-
-### Measurement Cadence
-- **Daily**: [Metrics tracked daily]
-- **Weekly**: [Metrics tracked weekly]
-- **Monthly**: [Metrics tracked monthly]
-
-## Legacy Context
-
-### Existing Assets
-- [Reusable assets or resources]
-- [Relevant past projects or experience]
-
-## TODO:SPEC-BACKLOG-001 Next SPEC Candidates
-
-1. **SPEC-001**: [First feature to implement]
-2. **SPEC-002**: [Second feature to implement]
-3. **SPEC-003**: [Third feature to implement]
-
-## EARS Requirement Authoring Guide
-
-### EARS (Easy Approach to Requirements Syntax)
-
-Use these EARS patterns to keep SPEC requirements structured:
-
-#### EARS Patterns
-1. **Ubiquitous Requirements**: The system shall provide [capability].
-2. **Event-driven Requirements**: WHEN [condition], the system shall [behaviour].
-3. **State-driven Requirements**: WHILE [state], the system shall [behaviour].
-4. **Optional Features**: WHERE [condition], the system may [behaviour].
-5. **Constraints**: IF [condition], the system shall enforce [constraint].
-
-#### Sample Application
-```markdown
-### Ubiquitous Requirements (Foundational)
-- The system shall provide user management capabilities.
-
-### Event-driven Requirements
-- WHEN a user signs up, the system shall send a welcome email.
-
-### State-driven Requirements
-- WHILE a user remains logged in, the system shall display a personalized dashboard.
-
-### Optional Features
-- WHERE an account is premium, the system may offer advanced features.
-
-### Constraints
-- IF an account is locked, the system shall reject login attempts.
-```
-
----
-
-_This document serves as the baseline when `/alfred:1-plan` runs._

moai_adk/templates/.moai/project/structure.md

@@ -1,156 +0,0 @@
----
-id: STRUCTURE-001
-version: 0.1.1
-status: active
-created: 2025-10-01
-updated: 2025-10-17
-author: @architect
-priority: medium
----
-
-# {{PROJECT_NAME}} Structure Design
-
-## HISTORY
-
-### v0.1.1 (2025-10-17)
-- **UPDATED**: Template version synced (v0.3.8)
-- **AUTHOR**: @Alfred
-- **SECTIONS**: Metadata standardization (single `author` field, added `priority`)
-
-### v0.1.0 (2025-10-01)
-- **INITIAL**: Authored the structure design document
-- **AUTHOR**: @architect
-- **SECTIONS**: Architecture, Modules, Integration, Traceability
-
----
-
-## @DOC:ARCHITECTURE-001 System Architecture
-
-### Architectural Strategy
-
-**[Describe the end-to-end architectural approach for the project]**
-
-```
-Project Architecture
-- [Layer 1]          # [Describe its responsibilities]
-- [Layer 2]          # [Describe its responsibilities]
-- [Layer 3]          # [Describe its responsibilities]
-- [Layer 4]          # [Describe its responsibilities]
-```
-
-**Rationale**: [Explain the trade-offs behind the chosen architecture]
-
-## @DOC:MODULES-001 Module Responsibilities
-
-### 1. [Primary Module 1]
-
-- **Responsibilities**: [Key duties of the module]
-- **Inputs**: [Data it consumes]
-- **Processing**: [Core processing steps]
-- **Outputs**: [Produced artifacts]
-
-| Component     | Role   | Key Capabilities |
-| ------------- | ------ | ---------------- |
-| [Component 1] | [Role] | [Feature list]   |
-| [Component 2] | [Role] | [Feature list]   |
-
-### 2. [Primary Module 2]
-
-- **Responsibilities**: [Key duties of the module]
-- **Inputs**: [Data it consumes]
-- **Processing**: [Core processing steps]
-- **Outputs**: [Produced artifacts]
-
-## @DOC:INTEGRATION-001 External Integrations
-
-### [External System 1] Integration
-
-- **Authentication**: [Method used]
-- **Data Exchange**: [Formats and protocols]
-- **Failure Handling**: [Fallback strategy]
-- **Risk Level**: [Risk profile and mitigation]
-
-### [External System 2] Integration
-
-- **Purpose**: [Why it is used]
-- **Dependency Level**: [Degree of reliance and alternatives]
-- **Performance Requirements**: [Latency, throughput, etc.]
-
-## @DOC:TRACEABILITY-001 Traceability Strategy
-
-### Applying the TAG Framework
-
-**Full TDD Alignment**: SPEC → Tests → Implementation → Documentation
-- `@SPEC:ID` (`.moai/specs/`) → `@TEST:ID` (`tests/`) → `@CODE:ID` (`src/`) → `@DOC:ID` (`docs/`)
-
-**Implementation Detail Levels**: Annotation within `@CODE:ID`
-- `@CODE:ID:API` – REST APIs, GraphQL endpoints
-- `@CODE:ID:UI` – Components, views, screens
-- `@CODE:ID:DATA` – Data models, schemas, types
-- `@CODE:ID:DOMAIN` – Business logic, domain rules
-- `@CODE:ID:INFRA` – Infrastructure, databases, integrations
-
-### Managing TAG Traceability (Code-Scan Approach)
-
-- **Verification**: Run `/alfred:3-sync`, which scans with `rg '@(SPEC|TEST|CODE|DOC):' -n`
-- **Coverage**: Full project source (`.moai/specs/`, `tests/`, `src/`, `docs/`)
-- **Cadence**: Validate whenever the code changes
-- **Code-First Principle**: TAG truth lives in the source itself
-
-## Legacy Context
-
-### Current System Snapshot
-
-**[Describe the existing system or assets]**
-
-```
-Current System/
-├── [Component 1]/     # [Current state]
-├── [Component 2]/     # [Current state]
-└── [Component 3]/     # [Current state]
-```
-
-### Migration Considerations
-
-1. **[Migration item 1]** – [Plan and priority]
-2. **[Migration item 2]** – [Plan and priority]
-3. **[Migration item 3]** – [Plan and priority]
-
-## TODO:STRUCTURE-001 Structural Improvements
-
-1. **Define module interfaces** – [Plan details]
-2. **Dependency management strategy** – [Plan details]
-3. **Scalability roadmap** – [Plan details]
-
-## EARS for Architectural Requirements
-
-### Applying EARS to Architecture
-
-Use EARS patterns to write clear architectural requirements:
-
-#### Architectural EARS Example
-```markdown
-### Ubiquitous Requirements (Baseline Architecture)
-- The system shall adopt a layered architecture.
-- The system shall maintain loose coupling across modules.
-
-### Event-driven Requirements
-- WHEN an external API call fails, the system shall execute fallback logic.
-- WHEN a data change event occurs, the system shall notify dependent modules.
-
-### State-driven Requirements
-- WHILE the system operates in scale-out mode, it shall load new modules dynamically.
-- WHILE in development mode, the system shall provide verbose debug information.
-
-### Optional Features
-- WHERE the deployment runs in the cloud, the system may use distributed caching.
-- WHERE high performance is required, the system may apply in-memory caching.
-
-### Constraints
-- IF the security level is elevated, the system shall encrypt all inter-module communication.
-- Each module shall keep cyclomatic complexity under 15.
-```
-
----
-
-_This structure informs the TDD implementation when `/alfred:2-run` runs._