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

moai_adk/templates/.moai/memory/GITFLOW-PROTECTION-POLICY.md

@@ -1,220 +0,0 @@
-# GitFlow Advisory Policy
-
-**Document ID**: @DOC:GITFLOW-POLICY-001  
-**Published**: 2025-10-17  
-**Status**: Advisory (recommended, not enforced)  
-**Scope**: Personal and Team modes
-
----
-
-## Overview
-
-MoAI-ADK **recommends** a GitFlow-inspired workflow. This policy shares best practices while letting teams adapt them as needed.
-
-## Key Recommendations
-
-### 1. Main Branch Access (Recommended)
-
-| Recommendation | Summary | Enforcement |
-|----------------|---------|-------------|
-| **Merge via develop** | Prefer merging `develop` into `main` | Advisory ⚠️ |
-| **Feature branches off develop** | Branch from `develop` and raise PRs back to `develop` | Advisory ⚠️ |
-| **Release process** | Release flow: `develop` → `main` (release engineer encouraged) | Advisory ⚠️ |
-| **Force push** | Warn when force-pushing, but allow it | Warning ⚠️ |
-| **Direct push** | Warn on direct pushes to `main`, but allow them | Warning ⚠️ |
-
-### 2. Git Workflow (Recommended)
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                RECOMMENDED GITFLOW                      │
-└─────────────────────────────────────────────────────────┘
-
-        develop (recommended base branch)
-          ↑     ↓
-    ┌─────────────────┐
-    │                 │
-    │   developer work │
-    │                 │
-    ↓                 ↑
-feature/SPEC-{ID}   [PR: feature -> develop]
-                     [code review + approval]
-                     [Merge to develop]
-
-    develop (stable)
-         ↓
-         │   (release manager prepares)
-         ↓
-    [PR: develop -> main]
-    [CI/CD validation]
-    [tag creation]
-         ↓
-       main (release)
-```
-
-**Flexibility**: Direct pushes to `main` are still possible, but the workflow above is preferred.
-
-## 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 (Legacy, Currently Disabled)
-
-- ❌ Block direct pushes to `main`
-- ❌ Block force pushes
-- ❌ Block merges into `main` from any branch other than `develop`
-
-### Advisory Mode (Active, v0.3.5+)
-
-- ⚠️ Warn but allow direct pushes to `main`
-- ⚠️ Warn but allow force pushes
-- ⚠️ Recommend best practices while preserving flexibility
-- ✅ Respect user judgment
-
----
-
-## 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: To promote best practices while respecting contributor flexibility and judgment.
-
----
-
-## 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  |
-
----
-
-**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/memory/spec-metadata.md

@@ -1,356 +0,0 @@
-# SPEC Metadata Structure Guide
-
-> **MoAI-ADK SPEC Metadata Standard**
->
-> Every SPEC document must follow this structure.
-
----
-
-## 📋 Metadata Overview
-
-SPEC metadata contains **7 required fields** and **9 optional fields**.
-
-### Full Example
-
-```yaml
----
-# Required Fields (7)
-id: AUTH-001                    # Unique SPEC ID
-version: 0.0.1                  # Semantic version (v0.0.1 = INITIAL, draft start)
-status: draft                   # draft|active|completed|deprecated
-created: 2025-09-15             # Creation date (YYYY-MM-DD)
-updated: 2025-09-15             # Last updated (YYYY-MM-DD; initially same as created)
-author: @Goos                   # Author (single GitHub handle)
-priority: high                  # low|medium|high|critical
-
-# Optional Fields – Classification/Meta
-category: security              # feature|bugfix|refactor|security|docs|perf
-labels:                         # Tags for search and grouping
-  - authentication
-  - jwt
-
-# Optional Fields – Relationships (Dependency Graph)
-depends_on:                     # SPECs this one depends on (optional)
-  - USER-001
-blocks:                         # SPECs blocked by this one (optional)
-  - AUTH-002
-related_specs:                  # Related SPECs (optional)
-  - TOKEN-002
-related_issue: "https://github.com/modu-ai/moai-adk/issues/123"
-
-# Optional Fields – Scope/Impact
-scope:
-  packages:                     # Impacted packages
-    - src/core/auth
-  files:                        # Key files (optional)
-    - auth-service.ts
-    - jwt-manager.ts
----
-```
-
----
-
-## Required Fields
-
-### 1. `id` – Unique SPEC Identifier
-- **Type**: string
-- **Format**: `<DOMAIN>-<NUMBER>`
-- **Examples**: `AUTH-001`, `INSTALLER-SEC-001`
-- **Rules**:
-  - Immutable once assigned
-  - Use three digits (001–999)
-  - Domain in uppercase; hyphens allowed
-  - Directory name: `.moai/specs/SPEC-{ID}/` (e.g., `.moai/specs/SPEC-AUTH-001/`)
-
-### 2. `version` – Semantic Version
-- **Type**: string (`MAJOR.MINOR.PATCH`)
-- **Default**: `0.0.1` (all SPECs start here, status: draft)
-- **Version Lifecycle**:
-  - **v0.0.1**: INITIAL – SPEC first draft (status: draft)
-  - **v0.0.x**: Draft refinements (increment PATCH when editing the SPEC)
-  - **v0.1.0**: TDD implementation complete (status: completed, updated via `/alfred:3-sync`)
-  - **v0.1.x**: Bug fixes or doc improvements (PATCH increment)
-  - **v0.x.0**: Feature additions or major enhancements (MINOR increment)
-  - **v1.0.0**: Stable release (production ready, explicit stakeholder approval required)
-
-### 3. `status` – Progress State
-- **Type**: enum
-- **Values**:
-  - `draft`: Authoring in progress
-  - `active`: Implementation underway
-  - `completed`: Implementation finished
-  - `deprecated`: Planned for retirement
-
-### 4. `created` – Creation Date
-- **Type**: date string
-- **Format**: `YYYY-MM-DD`
-- **Example**: `2025-10-06`
-
-### 5. `updated` – Last Modified Date
-- **Type**: date string
-- **Format**: `YYYY-MM-DD`
-- **Rule**: Update whenever the SPEC content changes.
-
-### 6. `author` – Primary Author
-- **Type**: string
-- **Format**: `@{GitHub ID}`
-- **Example**: `@Goos`
-- **Rules**:
-  - Single value only (no `authors` array)
-  - Prefix the GitHub handle with `@`
-  - Additional contributors belong in the HISTORY section
-
-### 7. `priority` – Work Priority
-- **Type**: enum
-- **Values**:
-  - `critical`: Immediate attention (security, severe defects)
-  - `high`: Major feature work
-  - `medium`: Enhancements
-  - `low`: Optimizations or documentation
-
----
-
-## Optional Fields
-
-### Classification / Meta
-
-#### 8. `category` – Change Type
-- **Type**: enum
-- **Values**:
-  - `feature`: New functionality
-  - `bugfix`: Defect resolution
-  - `refactor`: Structural improvements
-  - `security`: Security enhancements
-  - `docs`: Documentation updates
-  - `perf`: Performance optimizations
-
-#### 9. `labels` – Classification Tags
-- **Type**: array of strings
-- **Purpose**: Search, filtering, grouping
-- **Example**:
-  ```yaml
-  labels:
-    - installer
-    - template
-    - security
-  ```
-
-### Relationship Fields (Dependency Graph)
-
-#### 10. `depends_on` – Required SPECs
-- **Type**: array of strings
-- **Meaning**: SPECs that must be completed first
-- **Example**:
-  ```yaml
-  depends_on:
-    - USER-001
-    - AUTH-001
-  ```
-- **Use Case**: Determines execution order and parallelization.
-
-#### 11. `blocks` – Blocked SPECs
-- **Type**: array of strings
-- **Meaning**: SPECs that cannot proceed until this one is resolved
-- **Example**:
-  ```yaml
-  blocks:
-    - PAYMENT-003
-  ```
-
-#### 12. `related_specs` – Associated SPECs
-- **Type**: array of strings
-- **Meaning**: Related items without direct dependencies
-- **Example**:
-  ```yaml
-  related_specs:
-    - TOKEN-002
-    - SESSION-001
-  ```
-
-#### 13. `related_issue` – Linked GitHub Issue
-- **Type**: string (URL)
-- **Format**: Full GitHub issue URL
-- **Example**:
-  ```yaml
-  related_issue: "https://github.com/modu-ai/moai-adk/issues/123"
-  ```
-
-### Scope Fields (Impact Analysis)
-
-#### 14. `scope.packages` – Impacted Packages
-- **Type**: array of strings
-- **Meaning**: Packages or modules touched by the SPEC
-- **Example**:
-  ```yaml
-  scope:
-    packages:
-      - moai-adk-ts/src/core/installer
-      - moai-adk-ts/src/core/git
-  ```
-
-#### 15. `scope.files` – Key Files
-- **Type**: array of strings
-- **Meaning**: Primary files involved (for reference)
-- **Example**:
-  ```yaml
-  scope:
-    files:
-      - template-processor.ts
-      - template-security.ts
-  ```
-
----
-
-## Metadata Validation
-
-### Required Field Checks
-```bash
-# Verify that every SPEC includes the required fields
-rg "^(id|version|status|created|updated|author|priority):" .moai/specs/SPEC-*/spec.md
-
-# Identify SPECs missing the priority field
-rg -L "^priority:" .moai/specs/SPEC-*/spec.md
-```
-
-### Format Checks
-```bash
-# Ensure the author field uses @Handle format
-rg "^author: @[A-Z]" .moai/specs/SPEC-*/spec.md
-
-# Ensure the version field follows 0.x.y
-rg "^version: 0\.\d+\.\d+" .moai/specs/SPEC-*/spec.md
-```
-
----
-
-## Migration Guide
-
-### Updating Existing SPECs
-
-#### 1. Add the `priority` Field
-Add it if missing:
-```yaml
-priority: medium  # or low|high|critical
-```
-
-#### 2. Normalize the `author` Field
-- `authors: ["@goos"]` → `author: @Goos`
-- Convert lowercase handles to the canonical casing.
-
-#### 3. Add Optional Fields (Recommended)
-```yaml
-category: refactor
-labels:
-  - code-quality
-  - maintenance
-```
-
-### Updating config.json for Language Support (v0.4.2+)
-
-**Background**: MoAI-ADK v0.4.2 introduces conversation language selection in `/alfred:0-project`. Existing projects need to add language metadata to `.moai/config.json`.
-
-#### Migration Steps
-
-**For Existing Projects** (before v0.4.2):
-
-Current config.json structure:
-```json
-{
-  "project": {
-    "locale": "en",
-    "mode": "personal",
-    "language": "python"
-  }
-}
-```
-
-**Updated Structure** (v0.4.2+):
-```json
-{
-  "project": {
-    "locale": "en",
-    "mode": "personal",
-    "language": "python",
-    "conversation_language": "en",
-    "conversation_language_name": "English",
-    "codebase_languages": ["python"]
-  }
-}
-```
-
-#### New Fields
-
-| Field | Type | Required | Description | Example |
-|-------|------|----------|-------------|---------|
-| `conversation_language` | string (ISO 639-1 code) | ✅ Yes | Two-letter language code for Alfred dialogs | `"ko"`, `"en"`, `"ja"`, `"zh"` |
-| `conversation_language_name` | string | ✅ Yes | Display name of conversation language | `"Korean"`, `"English"` |
-| `codebase_languages` | array of strings | ✅ Yes | List of programming languages detected | `["python"]`, `["typescript", "python"]` |
-
-#### Manual Update Process
-
-1. Open `.moai/config.json`
-2. Add the three new fields under `project`:
-   ```json
-   "conversation_language": "en",
-   "conversation_language_name": "English",
-   "codebase_languages": ["python"]
-   ```
-3. Save and commit:
-   ```bash
-   git add .moai/config.json
-   git commit -m "chore: add language metadata to config.json for v0.4.2+"
-   ```
-
-#### Automated Update (via `/alfred:0-project`)
-
-Running `/alfred:0-project` on an existing project will:
-1. Detect current language settings
-2. Add new fields automatically
-3. Preserve existing values
-
-**No manual action required if running `/alfred:0-project` after upgrade.**
-
-#### Field Mapping (Legacy → New)
-
-| Old Field | New Field | Migration Rule |
-|-----------|-----------|-----------------|
-| `locale` | `conversation_language` | Keep as-is (or run `/alfred:0-project` to re-select) |
-| (none) | `conversation_language_name` | Auto-populate from locale mapping |
-| `language` | `codebase_languages` | Wrap in array: `"python"` → `["python"]` |
-
-#### Backward Compatibility
-
-- ✅ Projects without new fields will continue working
-- ⚠️ New language features (multilingual documentation) unavailable without migration
-- ✅ `/alfred:0-project` automatically migrates on next run
-- ✅ Auto-detection will prefer new fields if present
-
----
-
-## Design Principles
-
-### 1. DRY (Don't Repeat Yourself)
-- ❌ **Remove**: the `reference` field (every SPEC referenced the same master plan)
-- ✅ **Instead**: document project-level resources in README.md
-
-### 2. Context-Aware
-- Include only the necessary context.
-- Use optional fields only when they add value.
-
-### 3. Traceable
-- Use `depends_on`, `blocks`, and `related_specs` to map dependencies.
-- Automated tooling can detect cyclic references.
-
-### 4. Maintainable
-- Every field must be machine-verifiable.
-- Maintain consistent formatting for easy parsing.
-
-### 5. Simple First
-- Keep complexity low.
-- Limit to 7 required + 9 optional fields.
-- Expand gradually when justified.
-
----
-
-**Last Updated**: 2025-10-06  
-**Author**: @Alfred

moai_adk/templates/src/moai_adk/core/__init__.py

@@ -1,5 +0,0 @@
-"""MoAI-ADK core modules
-
-This package contains core functionality for MoAI-ADK including:
-- TAG validation and management
-"""

moai_adk/templates/src/moai_adk/core/tags/__init__.py

@@ -1,86 +0,0 @@
-#!/usr/bin/env python3
-# @CODE:DOC-TAG-004 | TAG validation core module (Components 1, 2, 3 & 4)
-"""TAG validation and management for MoAI-ADK
-
-This module provides TAG validation functionality for:
-- Pre-commit hook validation (Component 1)
-- CI/CD pipeline validation (Component 2)
-- Central validation system (Component 3)
-- Documentation & Reporting (Component 4)
-- TAG format checking
-- Duplicate detection
-- Orphan detection
-- Chain integrity validation
-"""
-
-# Component 1: Pre-commit validator
-# Component 2: CI/CD validator
-from .ci_validator import CIValidator
-from .pre_commit_validator import (
-    PreCommitValidator,
-    ValidationError,
-    ValidationResult,
-    ValidationWarning,
-)
-
-# Component 4: Documentation & Reporting
-from .reporter import (
-    CoverageAnalyzer,
-    CoverageMetrics,
-    InventoryGenerator,
-    MatrixGenerator,
-    ReportFormatter,
-    ReportGenerator,
-    ReportResult,
-    StatisticsGenerator,
-    StatisticsReport,
-    TagInventory,
-    TagMatrix,
-)
-
-# Component 3: Central validation system
-from .validator import (
-    CentralValidationResult,
-    CentralValidator,
-    ChainValidator,
-    DuplicateValidator,
-    FormatValidator,
-    OrphanValidator,
-    TagValidator,
-    ValidationConfig,
-    ValidationIssue,
-    ValidationStatistics,
-)
-
-__all__ = [
-    # Component 1
-    "PreCommitValidator",
-    "ValidationResult",
-    "ValidationError",
-    "ValidationWarning",
-    # Component 2
-    "CIValidator",
-    # Component 3
-    "ValidationConfig",
-    "TagValidator",
-    "DuplicateValidator",
-    "OrphanValidator",
-    "ChainValidator",
-    "FormatValidator",
-    "CentralValidator",
-    "CentralValidationResult",
-    "ValidationIssue",
-    "ValidationStatistics",
-    # Component 4
-    "TagInventory",
-    "TagMatrix",
-    "InventoryGenerator",
-    "MatrixGenerator",
-    "CoverageAnalyzer",
-    "StatisticsGenerator",
-    "ReportFormatter",
-    "ReportGenerator",
-    "CoverageMetrics",
-    "StatisticsReport",
-    "ReportResult",
-]