moai-adk 0.11.0__py3-none-any.whl → 0.12.0__py3-none-any.whl

moai_adk/templates/.moai/project/tech.md

@@ -0,0 +1,227 @@
+---
+id: TECH-001
+version: 0.1.1
+status: active
+created: 2025-10-01
+updated: 2025-10-17
+author: @tech-lead
+priority: medium
+---
+
+# {{PROJECT_NAME}} Technology Stack
+
+## 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 technology stack document
+- **AUTHOR**: @tech-lead
+- **SECTIONS**: Stack, Framework, Quality, Security, Deploy
+
+---
+
+## @DOC:STACK-001 Languages & Runtimes
+
+### Primary Language
+
+- **Language**: [Chosen primary language]
+- **Version Range**: [Supported versions]
+- **Rationale**: [Justification and trade-offs]
+- **Package Manager**: [Tool used to manage dependencies]
+
+### Multi-Platform Support
+
+| Platform    | Support Level | Validation Tooling  | Key Constraints |
+| ----------- | ------------- | ------------------- | --------------- |
+| **Windows** | [Supported?]  | [Validation method] | [Constraints]   |
+| **macOS**   | [Supported?]  | [Validation method] | [Constraints]   |
+| **Linux**   | [Supported?]  | [Validation method] | [Constraints]   |
+
+## @DOC:FRAMEWORK-001 Core Frameworks & Libraries
+
+### 1. Runtime Dependencies
+
+```json
+{
+  "dependencies": {
+    "[library1]": "[version]",
+    "[library2]": "[version]",
+    "[library3]": "[version]"
+  }
+}
+```
+
+### 2. Development Tooling
+
+```json
+{
+  "devDependencies": {
+    "[dev-tool1]": "[version]",
+    "[dev-tool2]": "[version]",
+    "[dev-tool3]": "[version]"
+  }
+}
+```
+
+### 3. Build System
+
+- **Build Tool**: [Selected build tool]
+- **Bundling**: [Bundler and configuration]
+- **Targets**: [Build targets such as browser, Node.js, etc.]
+- **Performance Goals**: [Desired build duration]
+
+## @DOC:QUALITY-001 Quality Gates & Policies
+
+### Test Coverage
+
+- **Target**: [Coverage percentage goal]
+- **Measurement Tool**: [Tooling used]
+- **Failure Response**: [Actions when coverage falls short]
+
+### Static Analysis
+
+| Tool           | Role      | Config File   | Failure Handling |
+| -------------- | --------- | ------------- | ---------------- |
+| [linter]       | [Purpose] | [config file] | [Action]         |
+| [formatter]    | [Purpose] | [config file] | [Action]         |
+| [type-checker] | [Purpose] | [config file] | [Action]         |
+
+### Automation Scripts
+
+```bash
+# Quality gate pipeline
+[test-command]                    # Run tests
+[lint-command]                    # Enforce code quality
+[type-check-command]              # Validate types
+[build-command]                   # Verify builds
+```
+
+## @DOC:SECURITY-001 Security Policy & Operations
+
+### Secret Management
+
+- **Policy**: [Approach to handling secrets]
+- **Tooling**: [Services or tools in use]
+- **Verification**: [Automation to validate compliance]
+
+### Dependency Security
+
+```json
+{
+  "security": {
+    "audit_tool": "[security-audit-tool]",
+    "update_policy": "[update-policy]",
+    "vulnerability_threshold": "[allowed-threshold]"
+  }
+}
+```
+
+### Logging Policy
+
+- **Log Levels**: [Define log levels]
+- **Sensitive Data Masking**: [Masking rules]
+- **Retention Policy**: [Log retention period]
+
+## @DOC:DEPLOY-001 Release Channels & Strategy
+
+### 1. Distribution Channels
+
+- **Primary Channel**: [Main release path]
+- **Release Procedure**: [Deployment process]
+- **Versioning Policy**: [Version management strategy]
+- **Rollback Strategy**: [Rollback plan]
+
+### 2. Developer Setup
+
+```bash
+# Developer mode setup
+[local-install-command]
+[dependency-install-command]
+[dev-environment-command]
+```
+
+### 3. CI/CD Pipeline
+
+| Stage     | Objective   | Tooling | Success Criteria |
+| --------- | ----------- | ------- | ---------------- |
+| [Stage 1] | [Objective] | [Tool]  | [Condition]      |
+| [Stage 2] | [Objective] | [Tool]  | [Condition]      |
+| [Stage 3] | [Objective] | [Tool]  | [Condition]      |
+
+## Environment Profiles
+
+### Development (`dev`)
+
+```bash
+export PROJECT_MODE=development
+export LOG_LEVEL=debug
+[dev-env-command]
+```
+
+### Test (`test`)
+
+```bash
+export PROJECT_MODE=test
+export LOG_LEVEL=info
+[test-env-command]
+```
+
+### Production (`production`)
+
+```bash
+export PROJECT_MODE=production
+export LOG_LEVEL=warning
+[prod-env-command]
+```
+
+## @CODE:TECH-DEBT-001 Technical Debt Management
+
+### Current Debt
+
+1. **[debt-item-1]** – [Description and priority]
+2. **[debt-item-2]** – [Description and priority]
+3. **[debt-item-3]** – [Description and priority]
+
+### Remediation Plan
+
+- **Short term (1 month)**: [Immediate fixes]
+- **Mid term (3 months)**: [Progressive improvements]
+- **Long term (6+ months)**: [Strategic upgrades]
+
+## EARS Technical Requirements Guide
+
+### Using EARS for the Stack
+
+Apply EARS patterns when documenting technical decisions and quality gates:
+
+#### Technology Stack EARS Example
+```markdown
+### Ubiquitous Requirements (Baseline)
+- The system shall guarantee TypeScript type safety.
+- The system shall provide cross-platform compatibility.
+
+### Event-driven Requirements
+- WHEN code is committed, the system shall run tests automatically.
+- WHEN a build fails, the system shall notify developers immediately.
+
+### State-driven Requirements
+- WHILE in development mode, the system shall offer hot reloading.
+- WHILE in production mode, the system shall produce optimized builds.
+
+### Optional Features
+- WHERE Docker is available, the system may support container-based deployment.
+- WHERE CI/CD is configured, the system may execute automated deployments.
+
+### Constraints
+- IF a dependency vulnerability is detected, the system shall halt the build.
+- Test coverage shall remain at or above 85%.
+- Build time shall not exceed 5 minutes.
+```
+
+---
+
+_This technology stack guides tool selection and quality gates when `/alfred:2-run` runs._

moai_adk/templates/CLAUDE.md

@@ -117,22 +117,102 @@ Alfred follows a systematic **4-step workflow** for all user requests to ensure
 
 ---
 
+## 🛠️ Auto-Fix & Merge Conflict Protocol
+
+When Alfred detects issues that could automatically fix code (merge conflicts, overwritten changes, deprecated code, etc.), follow this protocol BEFORE making any changes:
+
+### Step 1: Analysis & Reporting
+- Analyze the problem thoroughly using git history, file content, and logic
+- Write a clear report (plain text, NO markdown) explaining:
+  - Root cause of the issue
+  - Files affected
+  - Proposed changes
+  - Impact analysis
+
+Example Report Format:
+```
+    Detected Merge Conflict:
+
+    Root Cause:
+    - Commit c054777b removed language detection from develop
+    - Merge commit e18c7f98 (main → develop) re-introduced the line
+
+    Impact:
+    - .claude/hooks/alfred/shared/handlers/session.py
+    - src/moai_adk/templates/.claude/hooks/alfred/shared/handlers/session.py
+
+    Proposed Fix:
+    - Remove detect_language() import and call
+    - Delete "🐍 Language: {language}" display line
+    - Synchronize both local + package templates
+```
+
+### Step 2: User Confirmation (AskUserQuestion)
+- Present the analysis to the user
+- Use AskUserQuestion to get explicit approval
+- Options should be clear: "Should I proceed with this fix?" with YES/NO choices
+- Wait for user response before proceeding
+
+### Step 3: Execute Only After Approval
+- Only modify files after user confirms
+- Apply changes to both local project AND package templates
+- Maintain consistency between `/` and `src/moai_adk/templates/`
+
+### Step 4: Commit with Full Context
+- Create commit with detailed message explaining:
+  - What problem was fixed
+  - Why it happened
+  - How it was resolved
+- Reference the conflict commit if applicable
+
+### Critical Rules
+- ❌ NEVER auto-modify without user approval
+- ❌ NEVER skip the report step
+- ✅ ALWAYS report findings first
+- ✅ ALWAYS ask for user confirmation (AskUserQuestion)
+- ✅ ALWAYS update both local + package templates together
+
+---
+
 ## 📊 Reporting Style
 
-**CRITICAL RULE**: Alfred and all Sub-agents MUST output reports/completion notices in **direct markdown format**.
+**CRITICAL RULE**: Distinguish between screen output (user-facing) and internal documents (files).
+
+### Output Format Rules
+- **Screen output to user**: Plain text (NO markdown syntax)
+- **Internal documents** (files in `.moai/docs/`, `.moai/reports/`): Markdown format
+- **Code comments and git commits**: English, clear structure
+
+### Screen Output to User (Plain Text)
+
+**When responding directly to user in chat/prompt:**
+
+Use plain text format (NO markdown headers, tables, or special formatting):
+
+Example:
+```
+Detected Merge Conflict:
+
+Root Cause:
+- Commit c054777b removed language detection from develop
+- Merge commit e18c7f98 re-introduced the line
+
+Impact Range:
+- .claude/hooks/alfred/shared/handlers/session.py
+- src/moai_adk/templates/.claude/hooks/alfred/shared/handlers/session.py
+
+Proposed Actions:
+- Remove detect_language() import and call
+- Delete language display line
+- Synchronize both files
+```
 
-### ✅ Correct Report Output Pattern
+### Internal Documents (Markdown Format)
 
-**Output directly in markdown for these cases:**
+**When creating files in `.moai/docs/`, `.moai/reports/`, `.moai/analysis/`:**
 
-1. **Task Completion Report** - After implementation, testing, verification
-2. **Session Finalization** - After `/alfred:3-sync` completion, PR merge
-3. **Progress Summary** - Phase-by-phase status updates
-4. **Next Steps Guidance** - Recommendations for user
-5. **Analysis Results Report** - Code quality, architecture analysis
-6. **Validation Results Summary** - TRUST 5, @TAG verification
+Use markdown format with proper structure:
 
-**Output Format**:
 ```markdown
 ## 🎊 Task Completion Report
 

moai_adk/templates/workflows/go-tag-validation.yml

@@ -0,0 +1,130 @@
+# @CODE:LANG-001-GO | SPEC: SPEC-LANGUAGE-DETECTION-001.md | TEST: tests/test_workflows.py
+# Go Project TAG Validation Workflow
+# Automatically validates TAGs with go test, golangci-lint, and coverage
+
+name: TAG Validation (Go)
+
+on:
+  push:
+    branches: [main, develop, feature/**]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Validate TAGs - Go ${{ matrix.go-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        go-version: ['1.22', '1.23']
+      fail-fast: false
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go ${{ matrix.go-version }}
+        uses: actions/setup-go@v6
+        with:
+          go-version: ${{ matrix.go-version }}
+          cache: true
+
+      - name: Cache Go modules
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/go-build
+            ~/go/pkg/mod
+          key: go-${{ runner.os }}-${{ matrix.go-version }}-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            go-${{ runner.os }}-${{ matrix.go-version }}-
+            go-${{ runner.os }}-
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Verify dependencies
+        run: go mod verify
+
+      - name: Run go fmt
+        run: |
+          FMT_OUTPUT=$(gofmt -l .)
+          if [ -n "$FMT_OUTPUT" ]; then
+            echo "Files need formatting:"
+            echo "$FMT_OUTPUT"
+            exit 1
+          fi
+
+      - name: Run golangci-lint
+        uses: golangci/golangci-lint-action@v6
+        with:
+          version: latest
+          args: --timeout=5m
+
+      - name: Run tests with coverage
+        run: |
+          go test -v -race -coverprofile=coverage.out -covermode=atomic ./...
+          go tool cover -func=coverage.out
+
+      - name: Check coverage threshold
+        run: |
+          COVERAGE=$(go tool cover -func=coverage.out | grep total | awk '{print $3}' | sed 's/%//')
+          echo "Total coverage: ${COVERAGE}%"
+          if (( $(echo "$COVERAGE < 75" | bc -l) )); then
+            echo "❌ Coverage ${COVERAGE}% is below 75% threshold"
+            exit 1
+          fi
+          echo "✅ Coverage ${COVERAGE}% meets 75% threshold"
+
+      - name: Upload coverage reports
+        if: matrix.go-version == '1.23'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report-go
+          path: coverage.out
+
+      - name: Comment PR with coverage
+        if: github.event_name == 'pull_request' && matrix.go-version == '1.23'
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.out
+          flags: go
+          fail_ci_if_error: false
+
+      - name: Run go vet
+        run: go vet ./...
+
+      - name: Build project
+        run: go build -v ./...
+
+  quality-gate:
+    name: Quality Gate Summary
+    needs: validate
+    runs-on: ubuntu-latest
+    if: always()
+
+    steps:
+      - name: Check validation results
+        run: |
+          if [ "${{ needs.validate.result }}" != "success" ]; then
+            echo "❌ TAG validation failed"
+            exit 1
+          fi
+          echo "✅ TAG validation passed"
+
+      - name: Quality metrics summary
+        run: |
+          echo "## Quality Metrics Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ Go tests passed" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ Code coverage ≥ 75%" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ Linting passed (golangci-lint)" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ Formatting checked (gofmt)" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ Build successful" >> $GITHUB_STEP_SUMMARY

moai_adk/templates/workflows/javascript-tag-validation.yml

@@ -0,0 +1,135 @@
+# @CODE:LANG-001-JAVASCRIPT | SPEC: SPEC-LANGUAGE-DETECTION-001.md | TEST: tests/test_workflows.py
+# JavaScript Project TAG Validation Workflow
+# Automatically validates TAGs in JavaScript projects with npm/yarn/pnpm auto-detection
+
+name: TAG Validation (JavaScript)
+
+on:
+  push:
+    branches: [main, develop, feature/**]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Validate TAGs - Node ${{ matrix.node-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: ['20', '22']
+      fail-fast: false
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Detect package manager
+        id: detect-pm
+        run: |
+          if [ -f "bun.lockb" ]; then
+            echo "manager=bun" >> $GITHUB_OUTPUT
+            echo "lockfile=bun.lockb" >> $GITHUB_OUTPUT
+          elif [ -f "pnpm-lock.yaml" ]; then
+            echo "manager=pnpm" >> $GITHUB_OUTPUT
+            echo "lockfile=pnpm-lock.yaml" >> $GITHUB_OUTPUT
+          elif [ -f "yarn.lock" ]; then
+            echo "manager=yarn" >> $GITHUB_OUTPUT
+            echo "lockfile=yarn.lock" >> $GITHUB_OUTPUT
+          else
+            echo "manager=npm" >> $GITHUB_OUTPUT
+            echo "lockfile=package-lock.json" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Setup package manager cache
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: ${{ steps.detect-pm.outputs.manager }}
+
+      - name: Install pnpm (if needed)
+        if: steps.detect-pm.outputs.manager == 'pnpm'
+        run: npm install -g pnpm
+
+      - name: Install Bun (if needed)
+        if: steps.detect-pm.outputs.manager == 'bun'
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: |
+          case "${{ steps.detect-pm.outputs.manager }}" in
+            npm)
+              npm ci
+              ;;
+            yarn)
+              yarn install --frozen-lockfile
+              ;;
+            pnpm)
+              pnpm install --frozen-lockfile
+              ;;
+            bun)
+              bun install --frozen-lockfile
+              ;;
+          esac
+
+      - name: Run linting
+        run: |
+          if [ -f "biome.json" ]; then
+            npx @biomejs/biome check src/
+          elif command -v eslint &> /dev/null; then
+            npm run lint || npx eslint src/
+          fi
+        continue-on-error: false
+
+      - name: Run tests with coverage
+        run: npm test -- --coverage --coverage-threshold=80
+        continue-on-error: false
+
+      - name: Upload coverage reports
+        if: matrix.node-version == '22'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report-javascript
+          path: coverage/
+
+      - name: Comment PR with coverage
+        if: github.event_name == 'pull_request' && matrix.node-version == '22'
+        uses: ArtiomTr/jest-coverage-report-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          threshold: 80
+
+  quality-gate:
+    name: Quality Gate Summary
+    needs: validate
+    runs-on: ubuntu-latest
+    if: always()
+
+    steps:
+      - name: Check validation results
+        run: |
+          if [ "${{ needs.validate.result }}" != "success" ]; then
+            echo "❌ TAG validation failed"
+            exit 1
+          fi
+          echo "✅ TAG validation passed"
+
+      - name: Quality metrics summary
+        run: |
+          echo "## Quality Metrics Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ JavaScript tests passed" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ Code coverage ≥ 80%" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ Linting passed" >> $GITHUB_STEP_SUMMARY
+          echo "- ✅ TAG chain validated" >> $GITHUB_STEP_SUMMARY