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

moai_adk/templates/.moai/memory/DEVELOPMENT-GUIDE.md

@@ -0,0 +1,344 @@
+# {{PROJECT_NAME}} Development Guide
+
+> "No spec, no code. No tests, no implementation."
+
+This unified guardrail applies to every agent and developer who uses the MoAI-ADK universal development toolkit. The Python-based toolkit supports all major programming languages and enforces a SPEC-first TDD methodology with @TAG traceability. English is the default working language.
+
+---
+
+## SPEC-First TDD Workflow
+
+### Core Development Loop (3 Steps)
+
+1. **Write the SPEC** (`/alfred:1-plan`) → no code without a spec
+2. **Implement with TDD** (`/alfred:2-run`) → no implementation without tests
+3. **Sync Documentation** (`/alfred:3-sync`) → no completion without traceability
+
+### On-Demand Support
+
+- **Debugging**: summon `@agent-debug-helper` when failures occur
+- **CLI Commands**: init, doctor, status, update, restore, help, version
+- **System Diagnostics**: auto-detect language tooling and verify prerequisites
+
+Every change must comply with the @TAG system, SPEC-derived requirements, and language-specific TDD practices.
+
+### EARS Requirement Authoring
+
+**EARS (Easy Approach to Requirements Syntax)** provides a disciplined method for writing requirements.
+
+#### Five 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].
+
+#### Practical Example
+```markdown
+### Ubiquitous Requirements (Baseline)
+- The system shall provide user authentication.
+
+### Event-driven Requirements
+- WHEN a user logs in with valid credentials, the system shall issue a JWT token.
+- WHEN a token expires, the system shall return a 401 error.
+
+### State-driven Requirements
+- WHILE the user remains authenticated, the system shall allow access to protected resources.
+
+### Optional Features
+- WHERE a refresh token is present, the system may issue a new access token.
+
+### Constraints
+- IF an invalid token is supplied, the system shall deny access.
+- Access tokens shall not exceed a 15-minute lifetime.
+```
+
+---
+
+## Context Engineering
+
+MoAI-ADK follows Anthropic's principles from “Effective Context Engineering for AI Agents” to keep context lean and relevant.
+
+### 1. JIT (Just-in-Time) Retrieval
+
+**Principle**: Load documents only when needed to minimize initial context load.
+
+**Alfred’s JIT Strategy**:
+
+| Command          | Required Load    | Optional Load                    | Timing                             |
+| ---------------- | ---------------- | -------------------------------- | ---------------------------------- |
+| `/alfred:1-plan` | product.md       | structure.md, tech.md            | While discovering SPEC candidates  |
+| `/alfred:2-run`  | SPEC-XXX/spec.md | development-guide.md             | At the start of TDD implementation |
+| `/alfred:3-sync` | sync-report.md   | TAG chain validation (`rg` scan) | During documentation sync          |
+
+**Implementation Notes**:
+- Alfred uses the `Read` tool to load only the necessary documents at command time.
+- Agents request only the documents relevant to their current task.
+- The five documents listed in CLAUDE.md “Memory Strategy” are always loaded.
+
+### Context Engineering Checklist
+
+**When designing commands**:
+- [ ] JIT: Do we load only the required documents?
+- [ ] Optional Load: Do we load documents conditionally?
+
+**When designing agents**:
+- [ ] Minimum tools: Does the YAML frontmatter declare only the needed tools?
+- [ ] Clear roles: Does each agent maintain a single responsibility?
+
+---
+
+## TRUST Principles (5 Pillars)
+
+### T – Test-Driven Development (SPEC-Aligned)
+
+**SPEC → Test → Code Cycle**:
+
+- **SPEC**: Author detailed specifications first with `@SPEC:ID` tags (EARS format).
+- **RED**: `@TEST:ID` – write failing tests tied to SPEC requirements and confirm failure.
+- **GREEN**: `@CODE:ID` – implement the minimal code that passes the tests and satisfies the SPEC.
+- **REFACTOR**: `@CODE:ID` – improve the code while preserving SPEC compliance, then document with `@DOC:ID`.
+
+**Language-Specific TDD Tooling**:
+
+- **Python**: pytest + SPEC-based test cases (with mypy type hints)
+- **TypeScript**: Vitest + SPEC-driven suites (strict typing)
+- **Java**: JUnit + SPEC annotations (behaviour-driven tests)
+- **Go**: go test + SPEC table-driven tests (interface adherence)
+- **Rust**: cargo test + SPEC doc tests (trait validation)
+- **Ruby**: RSpec + SPEC-based BDD scenarios
+
+Each test links SPEC requirements to implementations via `@TEST:ID → @CODE:ID`.
+
+### R – Requirement-Driven Readability
+
+**SPEC-Aligned Clean Code**:
+
+- Functions implement SPEC requirements directly (≤ 50 LOC per function).
+- Names mirror SPEC terminology and domain language.
+- Code structure reflects SPEC design decisions.
+- Comments are limited to SPEC clarifications and @TAG references.
+
+**Language-Specific SPEC Implementation**:
+
+- **Python**: Type hints mirroring SPEC interfaces + mypy validation
+- **TypeScript**: Strict interfaces that match SPEC contracts
+- **Java**: Classes implementing SPEC components with strong typing
+- **Go**: Interfaces that satisfy SPEC requirements + gofmt
+- **Rust**: Types enforcing SPEC safety requirements + rustfmt
+- **Ruby**: Behaviour reflecting SPEC narratives + RuboCop validation
+
+Every code element must remain traceable back to the SPEC via @TAG comments.
+
+### U – Unified SPEC Architecture
+
+- **SPEC-Driven Complexity**: Each SPEC defines its complexity threshold. Exceeding it requires a new SPEC or a documented exception.
+- **SPEC vs. Implementation**: Keep authoring and implementation separate; never edit the SPEC mid-TDD cycle.
+- **Language Boundaries**: SPECs define boundaries across languages (Python modules, TypeScript interfaces, Java packages, Go packages, Rust crates, etc.).
+- **SPEC-Guided Architecture**: Domain boundaries follow the SPEC, not language conventions, with the @TAG system ensuring cross-language traceability.
+
+### S – SPEC-Compliant Security
+
+- **Security Requirements**: Every SPEC explicitly defines security needs, data sensitivity, and access control.
+- **Security by Design**: Implement security controls during the TDD cycle, not after completion.
+- **Language-Agnostic Security Patterns**:
+  - Input validation based on SPEC interface definitions
+  - Audit logging for SPEC-defined critical operations
+  - Access controls aligned with the SPEC permission model
+  - Secret management tailored to SPEC environment requirements
+
+### T – SPEC Traceability
+
+- **Spec-to-Code Traceability**: Every code change references SPEC IDs and requirements through the @TAG system.
+- **Three-Stage Workflow Trace**:
+  - `/alfred:1-plan`: Write SPECs with `@SPEC:ID` tags (`.moai/specs/`)
+  - `/alfred:2-run`: Implement via TDD with `@TEST:ID` (tests/) → `@CODE:ID` (src/)
+  - `/alfred:3-sync`: Sync documentation using `@DOC:ID` (docs/) and validate TAG coverage
+- **Code Scan Verification**: Guarantee TAG traceability by scanning the codebase directly with `rg '@(SPEC|TEST|CODE|DOC):' -n`, without intermediate caches.
+
+---
+
+## SPEC-First Mindset
+
+1. **SPEC-Led Decisions**: Reference an existing SPEC or author a new one before making any technical decision. Never implement without clear requirements.
+2. **SPEC Context Review**: Read the relevant SPEC documents before changing code, understand the @TAG relationships, and confirm compliance.
+3. **SPEC Communication**: Default to English for collaboration. SPEC documents should use precise technical terminology and plain, unambiguous explanations.
+
+## SPEC-TDD Workflow
+
+1. **Start with the SPEC**: Author or reference a SPEC before writing code. Use `/alfred:1-plan` to clarify requirements, design, and tasks.
+2. **Implement with TDD**: Follow the Red–Green–Refactor loop rigorously using `/alfred:2-run` with language-appropriate testing frameworks.
+3. **Maintain Traceability**: Run `/alfred:3-sync` to update documentation and preserve @TAG relationships between SPECs and code.
+
+## @TAG System
+
+### Core Chain
+
+```text
+@SPEC:ID → @TEST:ID → @CODE:ID → @DOC:ID
+```
+
+**Perfect TDD Alignment**:
+- `@SPEC:ID` (Preparation) – requirements authored with the EARS pattern
+- `@TEST:ID` (RED) – failing tests derived from the SPEC
+- `@CODE:ID` (GREEN + REFACTOR) – implementation and refactoring
+- `@DOC:ID` (Documentation) – live documents that capture the outcome
+
+### TAG Block Template
+
+> **📋 SPEC Metadata Standard (SSOT)**: see `SPEC-METADATA.md`
+
+**Every SPEC document must include YAML front matter and a HISTORY section**:
+- **Required Fields (7)**: id, version, status, created, updated, author, priority
+- **Optional Fields (9)**: category, labels, depends_on, blocks, related_specs, related_issue, scope
+- **HISTORY Section**: log every version change (mandatory)
+
+Find the complete template, field descriptions, and validation commands in `SPEC-METADATA.md`.
+
+**Quick Reference Example**:
+```yaml
+---
+id: AUTH-001
+version: 0.0.1
+status: draft
+created: 2025-09-15
+updated: 2025-09-15
+author: @Goos
+priority: high
+---
+
+# @SPEC:AUTH-001: JWT Authentication System
+
+## HISTORY
+### v0.0.1 (2025-09-15)
+- **INITIAL**: Authored the JWT authentication system SPEC
+...
+```
+
+**Source Code (`src/`)**:
+```text
+# @CODE:AUTH-001 | SPEC: SPEC-AUTH-001.md | TEST: tests/auth/service.test.ts
+```
+
+**Test Code (`tests/`)**:
+```text
+# @TEST:AUTH-001 | SPEC: SPEC-AUTH-001.md
+```
+
+### @CODE Subcategories (Comment Level)
+
+Document implementation details inside `@CODE:ID` blocks:
+- `@CODE:ID:API` – REST APIs, GraphQL endpoints
+- `@CODE:ID:UI` – UI components, views, screens
+- `@CODE:ID:DATA` – data models, schemas, types
+- `@CODE:ID:DOMAIN` – business logic, domain rules
+- `@CODE:ID:INFRA` – infrastructure, databases, integrations
+
+### TAG Usage Rules
+
+- **TAG ID Format**: `<DOMAIN>-<3 digits>` (e.g., `AUTH-003`) – immutable once created.
+- **Directory Naming**: `.moai/specs/SPEC-{ID}/` (required)
+  - ✅ Valid: `SPEC-AUTH-001/`, `SPEC-REFACTOR-001/`, `SPEC-UPDATE-REFACTOR-001/`
+  - ❌ Invalid: `AUTH-001/`, `SPEC-001-auth/`, `SPEC-AUTH-001-jwt/`
+  - **Composite Domains**: hyphenated combinations allowed (e.g., `UPDATE-REFACTOR-001`)
+  - **Guideline**: Prefer fewer than three hyphen segments for clarity
+- **TAG Contents**: May evolve freely; always record the rationale in HISTORY.
+- **Versioning**: Semantic Versioning (v0.0.1 → v0.1.0 → v1.0.0)
+  - See `SPEC-METADATA.md#versioning` for details.
+- **Duplicate Check**: Run `rg "@SPEC:{ID}" -n .moai/specs/` before creating a new TAG.
+- **TAG Validation**: `rg '@(SPEC|TEST|CODE|DOC):' -n .moai/specs/ tests/ src/ docs/`
+- **Version Alignment**: `rg "SPEC-{ID}.md v" -n`
+- **Code-First Principle**: The source of truth for TAGs lives in the codebase.
+
+### HISTORY Authoring Guide
+
+**Change Type Tags**:
+- `INITIAL`: First release (v1.0.0)
+- `ADDED`: New requirement or capability → increment MINOR
+- `CHANGED`: Adjusted behaviour → increment PATCH
+- `FIXED`: Bug or defect fix → increment PATCH
+- `REMOVED`: Removed capability → increment MAJOR
+- `BREAKING`: Backward-incompatible change → increment MAJOR
+- `DEPRECATED`: Marked for future removal
+
+**Required Metadata**:
+- `AUTHOR`: Contributor (GitHub ID)
+- `REVIEW`: Reviewer and approval status
+- `REASON`: Why the change was made (optional but recommended for significant updates)
+- `RELATED`: Linked issues/PRs (optional)
+
+**HISTORY Search Examples**:
+```bash
+# View the full change log for a TAG
+rg -A 20 "# @SPEC:AUTH-001" .moai/specs/SPEC-AUTH-001.md
+
+# Extract only the HISTORY section
+rg -A 50 "## HISTORY" .moai/specs/SPEC-AUTH-001.md
+
+# Check the latest entries
+rg "### v[0-9]" .moai/specs/SPEC-AUTH-001.md | head -3
+```
+
+---
+
+## Development Principles
+
+### Code Constraints
+
+- ≤ 300 LOC per file
+- ≤ 50 LOC per function
+- ≤ 5 parameters per function
+- Cyclomatic complexity ≤ 10
+
+### Quality Benchmarks
+
+- ≥ 85% test coverage
+- Use intention-revealing names
+- Prefer guard clauses
+- Leverage language-standard tooling
+
+### Refactoring Rules
+
+- **Rule of Three**: Plan refactoring when the same pattern appears a third time.
+- **Preparatory Refactoring**: Shape the code for easy change before applying the change.
+- **Tidy as You Go**: Fix small issues immediately; when scope expands, split into a dedicated effort.
+
+## Exception Handling
+
+When deviating from recommendations, document a waiver and attach it to the relevant PR, issue, or ADR.
+
+**Waiver Checklist**:
+
+- Justification and evaluated alternatives
+- Risks and mitigation plan
+- Temporary vs. permanent status
+- Expiry conditions and approver
+
+## Language Tooling Map
+
+- **Python**: pytest (tests), mypy (type checks), black (formatting)
+- **TypeScript**: Vitest (tests), Biome (lint + format)
+- **Java**: JUnit (tests), Maven/Gradle (build)
+- **Go**: go test (tests), gofmt (format)
+- **Rust**: cargo test (tests), rustfmt (format)
+- **Ruby**: RSpec (tests), RuboCop (lint + format), Bundler (packages)
+
+## Variable Role Reference
+
+| Role               | Description                        | Example                              |
+| ------------------ | ---------------------------------- | ------------------------------------ |
+| Fixed Value        | Constant after initialization      | `const MAX_SIZE = 100`               |
+| Stepper            | Changes sequentially               | `for (let i = 0; i < n; i++)`        |
+| Flag               | Boolean state indicator            | `let isValid = true`                 |
+| Walker             | Traverses a data structure         | `while (node) { node = node.next; }` |
+| Most Recent Holder | Holds the most recent value        | `let lastError`                      |
+| Most Wanted Holder | Holds optimal/maximum value        | `let bestScore = -Infinity`          |
+| Gatherer           | Accumulator                        | `sum += value`                       |
+| Container          | Stores multiple values             | `const list = []`                    |
+| Follower           | Previous value of another variable | `prev = curr; curr = next;`          |
+| Organizer          | Reorganizes data                   | `const sorted = array.sort()`        |
+| Temporary          | Temporary storage                  | `const temp = a; a = b; b = temp;`   |
+
+---
+
+This guide defines the standards for executing the three-stage MoAI-ADK pipeline.

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

@@ -0,0 +1,330 @@
+# 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.**