monoco-toolkit 0.3.9__py3-none-any.whl → 0.3.11__py3-none-any.whl

monoco/features/issue/linter.py

@@ -29,7 +29,7 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
 
     # 1. Collection Phase (Build Index)
     # Helper to collect issues from a project
-    def collect_project_issues(project_issues_root: Path, project_name: str = "local"):
+    def collect_project_issues(project_issues_root: Path, project_name: str = "local", include_archived: bool = False):
         project_issues = []
         project_diagnostics = []
         for subdir in ["Epics", "Features", "Chores", "Fixes", "Domains"]:
@@ -128,10 +128,30 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
                 else:
                     # Standard Issues (Epics/Features/etc)
                     files = []
-                    for status in ["open", "closed", "backlog"]:
-                        status_dir = d / status
-                        if status_dir.exists():
-                            files.extend(status_dir.rglob("*.md"))
+                    # Standard status directories
+                    status_dirs = ["open", "closed", "backlog"]
+                    # Include archived if requested (for full validation)
+                    if include_archived:
+                        status_dirs.append("archived")
+                    
+                    for item in d.iterdir():
+                        if item.is_dir():
+                            status = item.name.lower()
+                            if status in status_dirs:
+                                files.extend(item.rglob("*.md"))
+                            elif status != "archived": # archived is handled separately if include_archived
+                                # Report Illegal Directory immediately
+                                project_diagnostics.append(
+                                    Diagnostic(
+                                        range=Range(
+                                            start=Position(line=0, character=0),
+                                            end=Position(line=0, character=0),
+                                        ),
+                                        message=f"Illegal Directory: Issues should be in 'open/', 'closed/', or 'backlog/' directories, not '{status}/' directory.",
+                                        severity=DiagnosticSeverity.Error,
+                                        source="System",
+                                    )
+                                )
 
                     for f in files:
                         try:
@@ -283,12 +303,45 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
 
     # 2. Validation Phase
     valid_domains = set()
+    # Build list of actual IssueMetadata objects for domain governance checks
+    all_issue_metas = []
+    
     # Now validate
     for path, meta, project_name in all_issues:
         if meta == "DOMAIN":
             valid_domains.add(
                 project_name
             )  # Record the domain name (which was stored in project_name slot)
+        else:
+            all_issue_metas.append(meta)
+
+    # FEAT-0136: Project-Level Domain Governance Check
+    # Calculate scale metrics
+    num_issues = len(all_issue_metas)
+    num_epics = len([i for i in all_issue_metas if i.type == "epic"])
+    is_large_scale = num_issues > 128 or num_epics > 32
+    
+    # Check Domain Coverage for large-scale projects
+    if is_large_scale and num_epics > 0:
+        epics = [i for i in all_issue_metas if i.type == "epic"]
+        untracked_epics = [e for e in epics if not e.domains]
+        untracked_ratio = len(untracked_epics) / len(epics)
+        
+        # Rule: Untracked Epics / Total Epics <= 25%
+        if untracked_ratio > 0.25:
+            # Report this as a project-level diagnostic (attached to first epic or general)
+            diagnostics.append(
+                Diagnostic(
+                    range=Range(
+                        start=Position(line=0, character=0),
+                        end=Position(line=0, character=0),
+                    ),
+                    message=f"Domain Governance: Coverage is too low for a project of this scale ({len(untracked_epics)}/{len(epics)} Epics untracked). "
+                            f"At least 75% of Epics must have domains assigned.",
+                    severity=DiagnosticSeverity.Error,
+                    source="DomainGovernance",
+                )
+            )
 
     for path, meta, project_name in all_issues:
         if meta == "DOMAIN":
@@ -325,6 +378,7 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
 
         # A. Run Core Validator
         # Pass valid_domains kwarg (Validator needs update to accept it)
+        # FEAT-0136: Also pass all_issue_metas for domain governance checks
         file_diagnostics = validator.validate(
             meta,
             content,
@@ -332,6 +386,7 @@ def check_integrity(issues_root: Path, recursive: bool = False) -> List[Diagnost
             current_project=project_name,
             workspace_root=workspace_root_name,
             valid_domains=valid_domains,
+            all_issues=all_issue_metas,
         )
 
         # Add context to diagnostics (Path)

monoco/features/issue/models.py

@@ -67,12 +67,14 @@ class IssueType(str, Enum):
     FEATURE = "feature"
     CHORE = "chore"
     FIX = "fix"
+    ARCH = "arch"
 
 
 class IssueStatus(str, Enum):
     OPEN = "open"
     CLOSED = "closed"
     BACKLOG = "backlog"
+    ARCHIVED = "archived"
 
 
 class IssueStage(str, Enum):
@@ -222,8 +224,7 @@ class IssueMetadata(BaseModel):
             # Stage normalization
             if "stage" in v and isinstance(v["stage"], str):
                 v["stage"] = v["stage"].lower()
-                if v["stage"] == "todo":
-                    v["stage"] = "draft"
+
                 try:
                     v["stage"] = IssueStage(v["stage"])
                 except ValueError:

monoco/features/issue/resources/en/AGENTS.md

@@ -20,3 +20,112 @@ System for managing tasks using `monoco issue`.
      - 🛑 **NO** direct coding on `main`/`master` (Linter will fail).
      - **Prune Timing**: ONLY prune environment (branch/worktree) during `monoco issue close --prune`. NEVER prune at `submit` stage.
      - Must update `files` field after coding (via `sync-files` or manual).
+
+## Git Merge Strategy
+
+### Core Principles
+
+To ensure safe merging of Feature branches into the mainline and prevent "stale state pollution", the following merge strategy must be followed:
+
+#### 1. No Manual Merge
+
+- **🛑 STRICTLY FORBIDDEN**: Agents must NOT manually execute `git merge` to merge Feature branches
+- **🛑 STRICTLY FORBIDDEN**: Using `git pull origin main` followed by direct commits
+- **✅ ONLY AUTHORITATIVE PATH**: Must use `monoco issue close` for closing the loop
+
+#### 2. Safe Merge Flow
+
+The correct Issue closing workflow is as follows:
+
+```bash
+# 1. Ensure you're on main/master branch and code is merged
+$ git checkout main
+$ git pull origin main
+
+# 2. Confirm Feature branch changes are merged to mainline
+#    (via PR/MR or other code review process)
+
+# 3. Use monoco issue close to close Issue (prune by default)
+$ monoco issue close FEAT-XXXX --solution implemented
+
+# 4. To keep branch, use --no-prune
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+```
+
+#### 3. Conflict Resolution Principles
+
+When Feature branch conflicts with mainline:
+
+1. **Auto-merge Stop**: If `touched files` (Issue `files` field) conflict with mainline, automation tools **MUST IMMEDIATELY STOP** merging and throw a clear error.
+
+2. **Manual Cherry-Pick Mode**:
+   - Error message will instruct Agent to switch to manual Cherry-Pick mode
+   - **Core Principle**: Only pick valid changes belonging to this Feature, STRICTLY FORBIDDEN from overwriting updates to unrelated Issues on mainline
+   - Use `git cherry-pick <commit>` to apply valid commits one by one
+
+3. **Fallback Strategy**:
+   ```bash
+   # 1. Create temporary branch for conflict resolution
+   $ git checkout main
+   $ git checkout -b temp/FEAT-XXXX-resolve
+   
+   # 2. Cherry-pick valid commits one by one
+   $ git cherry-pick <commit-hash-1>
+   $ git cherry-pick <commit-hash-2>
+   
+   # 3. If conflicts occur, only keep changes from this Feature
+   #    Discard any modifications that would overwrite other Issue updates on mainline
+   
+   # 4. Merge temporary branch when done
+   $ git checkout main
+   $ git merge temp/FEAT-XXXX-resolve
+   
+   # 5. Close Issue
+   $ monoco issue close FEAT-XXXX --solution implemented
+   ```
+
+#### 4. Smart Atomic Merge Based on files Field
+
+The Issue's `files` field records the Actual Impact Scope of the Feature branch:
+
+- **Generation**: `monoco issue sync-files` uses `git diff --name-only base...target` logic
+- **Purpose**: Serves as a merge whitelist, only merging files in the list, filtering out implicit overwrites caused by "stale baseline"
+- **Limitation**: Cannot defend against explicit accidental modifications (e.g., inadvertently formatting other Issue files)
+
+**Future Enhancement**: Implement selective merge logic based on `files` list:
+```bash
+# Selective merge (planned)
+$ git checkout main
+$ git checkout feature/FEAT-XXXX -- <files...>
+```
+
+#### 5. Cleanup Strategy
+
+- **Default Cleanup**: `monoco issue close` executes `--prune` by default, deleting Feature branch/worktree
+- **Keep Branch**: To preserve branch, explicitly use `--no-prune`
+- **Force Cleanup**: Use `--force` to force delete unmerged branches (use with caution)
+
+```bash
+# Default branch cleanup
+$ monoco issue close FEAT-XXXX --solution implemented
+# ✔ Cleaned up: branch:feat/feat-XXXX-xxx
+
+# Keep branch
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+
+# Force cleanup (caution)
+$ monoco issue close FEAT-XXXX --solution implemented --force
+```
+
+### Summary
+
+| Operation | Command | Description |
+|-----------|---------|-------------|
+| Create Issue | `monoco issue create feature -t "Title"` | Create Issue before development |
+| Start Development | `monoco issue start FEAT-XXXX --branch` | Create Feature branch |
+| Sync Files | `monoco issue sync-files` | Update files field |
+| Submit Review | `monoco issue submit FEAT-XXXX` | Enter Review stage |
+| Close Issue | `monoco issue close FEAT-XXXX --solution implemented` | Only merge path |
+| Keep Branch | `monoco issue close ... --no-prune` | Close without deleting branch |
+
+> ⚠️ **WARNING**: Any manual merge operation bypassing `monoco issue close` may cause mainline state pollution and violate workflow compliance requirements.

monoco/features/issue/resources/en/{SKILL.md → skills/monoco_atom_issue/SKILL.md}

@@ -1,6 +1,8 @@
 ---
-name: monoco-issue
+name: monoco_atom_issue
 description: Official skill for Monoco Issue System. Treats Issues as Universal Atoms, managing the lifecycle of Epic/Feature/Chore/Fix.
+type: atom
+version: 1.0.0
 ---
 
 # Issue Management

monoco/features/issue/resources/en/skills/monoco_workflow_issue_creation/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: monoco_workflow_issue_creation
+description: Extract improvement clues from Memo, classify and create Issue Ticket (Copilot Mode)
+type: workflow
+domain: issue
+version: 1.0.0
+---
+
+# Issue Create Workflow
+
+Standardized workflow for extracting improvement clues from Memo, analyzing and creating structured Issue Tickets.
+
+**Applicable Scenario**: Copilot Mode (Human-led, AI-assisted)
+**Target Users**: Developers who need to quickly transform ideas/notes into actionable tasks
+
+## Workflow State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Extract: Read Memo
+    
+    Extract --> Classify: Identify Type
+    Extract --> Archive: No Value
+    
+    Classify --> Design: Architecture Design Required
+    Classify --> Direct: Create Directly
+    
+    Design --> Create: Design Complete
+    Direct --> Create: Create Directly
+    
+    Archive --> [*]: Archive Memo
+    Create --> [*]: Issue Creation Complete
+```
+
+## Execution Steps
+
+### 1. Extract
+
+- **Goal**: Extract key improvement clues from Memo
+- **Input**: Memo file or temporary notes
+- **Output**: Structured improvement clue list
+- **Checkpoints**:
+  - [ ] Run `monoco memo list` to view pending Memos
+  - [ ] Analyze improvement type and impact scope for each Memo
+  - [ ] Identify actionable improvements (not pure reference materials)
+  - [ ] Record improvement motivation and expected effects
+
+**Analysis Dimensions**:
+| Dimension | Question |
+|-----------|----------|
+| Value | What problem does this improvement solve? |
+| Scope | Which modules/features are affected? |
+| Urgency | Do it now or later? |
+| Feasibility | Is there enough information to start? |
+
+### 2. Classify
+
+- **Goal**: Determine Issue type and priority
+- **Checkpoints**:
+  - [ ] Determine if it's an architecture-level improvement (→ Epic)
+  - [ ] Determine if it's user value increment (→ Feature)
+  - [ ] Determine if it's engineering debt (→ Chore)
+  - [ ] Determine if it's a bug fix (→ Fix)
+  - [ ] Assess if pre-architecture design is required
+
+**Decision Branches**:
+
+| Condition | Type | Next Step |
+|-----------|------|-----------|
+| Architecture vision-level improvement, needs decomposition into multiple Features | Epic | → Design |
+| User deliverable value, with clear acceptance criteria | Feature | → Direct |
+| Engineering maintenance task, technical debt cleanup | Chore | → Direct |
+| Bug fix, with clear reproduction steps | Fix | → Direct |
+| Pure reference material, no direct improvement value | - | → Archive |
+| Requires architecture design to estimate effort | - | → Design |
+
+### 3. Design (Optional)
+
+- **Goal**: Preliminary architecture design for complex improvements
+- **Applicable**: Epic or large Feature
+- **Checkpoints**:
+  - [ ] Analyze existing architecture inheritance
+  - [ ] Determine technical solution direction
+  - [ ] Identify dependency relationships and risk points
+  - [ ] Estimate effort and milestones
+
+**Outputs**:
+- Architecture Decision Record (ADR) draft
+- Subtask decomposition suggestions
+- Dependency Issue list
+
+### 4. Create
+
+- **Goal**: Create Issue that meets specifications
+- **Checkpoints**:
+  - [ ] Run `monoco issue create <type> -t "Title"`
+  - [ ] Write clear description and background
+  - [ ] Define verifiable acceptance criteria (at least 2 Checkboxes)
+  - [ ] Set dependency relationships (if needed)
+  - [ ] Associate related Memo (if applicable)
+  - [ ] Run `monoco issue lint` to verify compliance
+
+**Issue Content Template**:
+
+```markdown
+## Objective
+Clearly describe the goal and expected outcome of this Issue.
+
+## Acceptance Criteria
+- [ ] Acceptance criterion 1
+- [ ] Acceptance criterion 2
+
+## Technical Tasks
+- [ ] Technical task 1
+- [ ] Technical task 2
+
+## Related
+- Parent: EPIC-XXXX (if applicable)
+- Related Memo: MEMO-XXXX (if applicable)
+```
+
+### 5. Archive (Optional)
+
+- **Goal**: Archive Memos with no direct improvement value
+- **Checkpoints**:
+  - [ ] Confirm Memo content is pure reference material
+  - [ ] Record archiving reason
+  - [ ] Update Memo status (if system supports)
+
+## Issue Type Guide
+
+| Type | Purpose | Prefix | Mindset | Example |
+|------|---------|--------|---------|---------|
+| Epic | Grand goals, vision container | EPIC- | Architect | Refactor core architecture |
+| Feature | User value increment | FEAT- | Product Owner | Add export functionality |
+| Chore | Engineering tasks | CHORE- | Builder | Upgrade dependency versions |
+| Fix | Bug fixes | FIX- | Debugger | Fix memory leak |
+
+## Related Commands
+
+```bash
+# View pending Memos
+monoco memo list
+
+# Create Issue
+monoco issue create feature -t "Title"
+monoco issue create chore -t "Title"
+monoco issue create fix -t "Title"
+monoco issue create epic -t "Title"
+
+# Verify Issue compliance
+monoco issue lint
+```
+
+## Relationship with flow_engineer
+
+This workflow complements `flow_engineer`:
+- `issue-create-workflow`: Focuses on Issue creation phase, transforming ideas into actionable tasks
+- `flow_engineer`: Focuses on code implementation phase, executing Investigate → Code → Test → Report → Submit
+
+## Copilot Mode Tips
+
+As an AI Copilot, you should:
+1. **Ask proactively**: When Memo content is unclear, ask human developers for intent
+2. **Provide options**: Give multiple classification suggestions with reasoning
+3. **Assist drafting**: Help write Issue descriptions and acceptance criteria
+4. **Remind compliance**: Ensure created Issues meet project specifications

monoco/features/issue/resources/en/skills/monoco_workflow_issue_development/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: monoco_workflow_issue_development
+description: Execute complete workflow for Issue development, testing, submission and review (Copilot Mode)
+type: workflow
+domain: issue
+version: 1.0.0
+---
+
+# Issue Develop Workflow
+
+Complete standardized workflow for Issue development, testing, submission, review and merge.
+
+**Applicable Scenario**: Copilot Mode (Human-led, AI-assisted)
+**Target Users**: Developers responsible for implementing features or fixing bugs
+
+## Workflow State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Setup: Start Development
+    
+    Setup --> Develop: Environment Ready
+    Setup --> Setup: Dependencies Not Met<br/>(Wait for Resolution)
+    
+    Develop --> Test: Coding Complete
+    Develop --> Develop: Needs Iteration<br/>(Continue Development)
+    
+    Test --> Submit: Tests Pass
+    Test --> Develop: Tests Fail<br/>(Fix Code)
+    
+    state "Review Loop" as ReviewLoop {
+        Submit --> Review: Submit for Review
+        Review --> Fix: Changes Required
+        Fix --> Submit: Resubmit
+    }
+    
+    Review --> Merge: Review Passed
+    
+    Merge --> [*]: Merge Complete
+```
+
+## Execution Steps
+
+### 1. Setup
+
+- **Goal**: Prepare development environment, ensure ready to code
+- **Checkpoints**:
+  - [ ] Run `monoco issue start <ID> --branch` to create feature branch
+  - [ ] Confirm branch is created and switched
+  - [ ] Verify not currently on main/master branch
+  - [ ] Check if dependency Issues are completed
+  - [ ] Confirm Issue is refined (has technical task list)
+
+**Environment Checklist**:
+| Check Item | Command/Method |
+|------------|----------------|
+| Current Branch | `git branch --show-current` |
+| Branch Status | `git status` |
+| Dependency Issues | `monoco issue show <ID>` |
+| Code Standards | Check project lint configuration |
+
+### 2. Develop
+
+- **Goal**: Implement feature or fix bug
+- **Strategy**: Iterative development, small commits
+- **Checkpoints**:
+  - [ ] Follow project code standards
+  - [ ] Write/update unit tests
+  - [ ] Commit code regularly (small commits)
+  - [ ] Update file tracking (`monoco issue sync-files`)
+  - [ ] Maintain code reviewability (single commit < 400 lines)
+
+**Development Principles**:
+| Principle | Description |
+|-----------|-------------|
+| Small Commits | Each commit is a logical unit |
+| Test First | Prioritize writing test cases |
+| Continuous Sync | Update file tracking promptly |
+| Stay Focused | Avoid unrelated changes |
+
+### 3. Test
+
+- **Goal**: Ensure code quality and functional correctness
+- **Checkpoints**:
+  - [ ] Run unit tests, ensure they pass
+  - [ ] Run integration tests (if applicable)
+  - [ ] Run code style checks (lint)
+  - [ ] Manually verify functionality (if needed)
+  - [ ] Check test coverage
+
+**Test Levels**:
+```
+Unit Test → Integration Test → E2E Test → Manual Verification
+   ↑          ↑            ↑            ↑
+ Required   Recommended   As Needed    As Needed
+```
+
+### 4. Submit
+
+- **Goal**: Prepare for code review
+- **Checkpoints**:
+  - [ ] Run `monoco issue lint` to check compliance
+  - [ ] Fix all Lint errors
+  - [ ] Update task list status (mark completed items)
+  - [ ] Write clear commit message
+  - [ ] Run `monoco issue submit <ID>`
+
+**Commit Message Specification**:
+```
+<type>(<scope>): <subject>
+
+<body>
+
+Refs: <ISSUE-ID>
+```
+
+| Type | Purpose |
+|------|---------|
+| feat | New feature |
+| fix | Bug fix |
+| docs | Documentation update |
+| style | Code formatting |
+| refactor | Refactoring |
+| test | Test related |
+| chore | Build/tools |
+
+### 5. Review
+
+- **Goal**: Code quality and process compliance check
+- **Checkpoints**:
+  - [ ] Is functionality correctly implemented
+  - [ ] Does code meet design specifications
+  - [ ] Are tests sufficient
+  - [ ] Is documentation updated
+  - [ ] Does it follow project standards
+
+**Review Dimensions**:
+| Dimension | Check Content |
+|-----------|---------------|
+| Correctness | Does functionality work as expected |
+| Design | Does it meet architecture design |
+| Testing | Is test coverage sufficient |
+| Standards | Does it follow code standards |
+| Documentation | Is documentation updated |
+| Performance | Are there obvious performance issues |
+| Security | Are there security risks |
+
+### 6. Merge
+
+- **Goal**: Complete Issue, merge code
+- **Checkpoints**:
+  - [ ] Code has passed review
+  - [ ] All CI checks pass
+  - [ ] Code is merged to main branch
+  - [ ] Run `monoco issue close <ID> --solution completed --prune`
+  - [ ] Verify branch is cleaned up
+  - [ ] Update Review Comments (record review feedback)
+
+## Decision Branches
+
+| Condition | Action |
+|-----------|--------|
+| Dependency Issues not completed | Return to Setup, wait for dependencies |
+| Tests fail | Return to Develop, fix code |
+| Lint fails | Fix compliance issues, resubmit |
+| Review requires changes | Return to Fix, modify per feedback |
+| Review passed | Enter Merge, merge and cleanup |
+
+## Compliance Requirements
+
+- **Prohibited**: Directly modify code on main/master branch
+- **Required**: Use `monoco issue start --branch` to create feature branch
+- **Required**: All unit tests must pass before Submit
+- **Required**: Each Issue must have at least 2 Checkboxes
+- **Required**: Review/Done phase must include Review Comments
+- **Recommended**: Small commits, frequently sync file tracking
+
+## Related Commands
+
+```bash
+# Start development
+monoco issue start FEAT-0001 --branch
+
+# Sync file tracking
+monoco issue sync-files
+
+# Check compliance
+monoco issue lint
+
+# Submit for review
+monoco issue submit FEAT-0001
+
+# Close Issue
+monoco issue close FEAT-0001 --solution completed --prune
+```
+
+## Relationship with flow_engineer
+
+The relationship between this workflow and `flow_engineer`:
+
+```
+issue-develop-workflow          flow_engineer
+       │                              │
+       ├── Setup ─────────────────────┤
+       ├── Develop ←──────────────────┤ Investigate → Code → Test
+       ├── Test ──────────────────────┤
+       ├── Submit ────────────────────┤ Report → Submit
+       ├── Review ────────────────────┤
+       └── Merge ─────────────────────┤
+```
+
+- `issue-develop-workflow`: Focuses on Issue-level process management
+- `flow_engineer`: Focuses on specific technical process for code implementation
+
+During the Develop phase, developers should follow `flow_engineer`'s Investigate → Code → Test → Report → Submit process.
+
+## Copilot Mode Tips
+
+As an AI Copilot, you should:
+1. **Assist coding**: Help implement features, fix bugs
+2. **Code review**: Pre-review before submission to find potential issues
+3. **Test assistance**: Help write test cases, ensure coverage
+4. **Compliance check**: Remind developers to follow project standards
+5. **Documentation sync**: Assist in updating related documentation