@flydocs/cli 0.6.0-alpha.20 → 0.6.0-alpha.22

package/template/.claude/hooks/stop-gate.py

@@ -16,6 +16,24 @@ import re
 import sys
 from pathlib import Path
 
+DEBUG_HOOK = os.environ.get('DEBUG_HOOK', '0') == '1'
+SCRIPT_DIR = Path(__file__).parent.resolve()
+DEBUG_LOG = SCRIPT_DIR.parent / 'logs' / 'hook-debug.log'
+
+
+def debug_log(message: str) -> None:
+    """Write debug message to log file if DEBUG_HOOK is enabled."""
+    if not DEBUG_HOOK:
+        return
+    try:
+        DEBUG_LOG.parent.mkdir(parents=True, exist_ok=True)
+        from datetime import datetime
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        with open(DEBUG_LOG, 'a') as f:
+            f.write(f'[{timestamp}] [stop-gate] {message}\n')
+    except (OSError, IOError):
+        pass
+
 ISSUE_ID_PATTERN = re.compile(r"[A-Z]+-[0-9]+")
 CHECKBOX_DONE = re.compile(r"- \[x\]", re.IGNORECASE)
 CHECKBOX_ALL = re.compile(r"- \[[ x]\]", re.IGNORECASE)
@@ -73,6 +91,29 @@ def main():
         sys.exit(0)
 
     status = status_text.strip().upper()
+    debug_log(f"Issue {issue_id} status={status}")
+
+    # -- READY: warn that transition to IMPLEMENTING was missed --
+    if status == "READY":
+        # Check if any code edits happened (heuristic: git has uncommitted changes)
+        try:
+            import subprocess
+            result = subprocess.run(
+                ["git", "diff", "--quiet"], capture_output=True, timeout=5
+            )
+            has_changes = result.returncode != 0
+        except (FileNotFoundError, subprocess.TimeoutExpired, subprocess.SubprocessError):
+            has_changes = False
+
+        if has_changes:
+            msg = (
+                "Issue {} is still in READY but code changes were made. "
+                "Transition to IMPLEMENTING before continuing:\n"
+                "  python3 .claude/skills/flydocs-workflow/scripts/issues.py "
+                "transition {} IMPLEMENTING \"Starting implementation\""
+            ).format(issue_id, issue_id)
+            sys.stderr.write(msg)
+            sys.exit(2)
 
     # -- IMPLEMENTING: block completion --
     if status == "IMPLEMENTING":
@@ -85,22 +126,34 @@ def main():
         sys.stderr.write(msg)
         sys.exit(2)
 
-    # -- REVIEW: warn on incomplete acceptance criteria --
+    # -- REVIEW: block on incomplete acceptance criteria --
     if status == "REVIEW":
         ac_text = read_file_safe(session_dir / "acceptance-criteria.md")
         if ac_text:
             total = len(CHECKBOX_ALL.findall(ac_text))
             done = len(CHECKBOX_DONE.findall(ac_text))
             if total > 0 and done < total:
-                result = {
-                    "hookSpecificOutput": {
-                        "additionalContext": (
-                            "Warning: {}/{} acceptance criteria checked "
-                            "for {}. Consider verifying remaining criteria."
-                        ).format(done, total, issue_id)
-                    }
-                }
-                print(json.dumps(result))
+                msg = (
+                    "Issue {}: {}/{} acceptance criteria checked. "
+                    "All AC must be verified before completion. "
+                    "Update the issue description with checked criteria:\n"
+                    "  python3 .claude/skills/flydocs-workflow/scripts/issues.py "
+                    "description {} --text \"<updated description with checked AC>\""
+                ).format(issue_id, done, total, issue_id)
+                sys.stderr.write(msg)
+                sys.exit(2)
+
+    # -- BLOCKED: inform that issue needs unblocking --
+    if status == "BLOCKED":
+        result = {
+            "hookSpecificOutput": {
+                "additionalContext": (
+                    "Issue {} is BLOCKED. Resolve the blocker before continuing, "
+                    "then transition back to IMPLEMENTING."
+                ).format(issue_id)
+            }
+        }
+        print(json.dumps(result))
 
     sys.exit(0)
 

package/template/.claude/skills/flydocs-workflow/scripts/flydocs_api.py

@@ -306,6 +306,7 @@ class FlyDocsClient:
 
     def _cloud_create_issue(self, **kwargs: object) -> dict:
         relay = self.relay
+        auto_resolved: dict[str, str] = {}
         issue_input: dict = {
             "teamId": relay.team_id,
             "title": kwargs.get("title", ""),
@@ -316,17 +317,34 @@ class FlyDocsClient:
         if estimate:
             issue_input["estimate"] = estimate
 
-        # Labels
+        # Labels — category + triage + repo (auto-resolved)
         label_ids: list[str] = []
         issue_type = kwargs.get("issue_type", "")
         if isinstance(issue_type, str):
             cat_id = relay.get_category_label_id(issue_type)
             if cat_id:
                 label_ids.append(cat_id)
+                auto_resolved["categoryLabel"] = issue_type
         if kwargs.get("triage"):
             triage_id = relay.get_other_label_id("triage")
             if triage_id:
                 label_ids.append(triage_id)
+
+        # Repo label for multi-repo workspaces
+        repo_labels = relay.config.get("issueLabels", {}).get("repo", {})
+        topology = relay.config.get("topology", {})
+        topo_type = topology.get("type", 1)
+        if topo_type in (3, 4) and repo_labels:
+            # Detect current repo name from slug
+            slug = relay.repo_slug or ""
+            repo_name = slug.split("/")[-1] if "/" in slug else slug
+            for name, label_id in repo_labels.items():
+                if label_id and name.lower() in repo_name.lower():
+                    if label_id not in label_ids:
+                        label_ids.append(label_id)
+                        auto_resolved["repoLabel"] = name
+                    break
+
         if label_ids:
             issue_input["labelIds"] = label_ids
 
@@ -336,9 +354,19 @@ class FlyDocsClient:
             active = relay.workspace.get("activeProjects", [])
             if active:
                 project_id = active[0]
+                auto_resolved["project"] = "activeProjects"
         if project_id:
             issue_input["projectId"] = project_id
 
+        # Milestone
+        milestone_id = kwargs.get("milestone")
+        if not milestone_id:
+            milestone_id = relay.workspace.get("defaultMilestoneId")
+            if milestone_id:
+                auto_resolved["milestone"] = "defaultMilestoneId"
+        if milestone_id:
+            issue_input["projectMilestoneId"] = milestone_id
+
         # Assignee
         assignee = kwargs.get("assignee")
         if assignee and isinstance(assignee, str):
@@ -348,12 +376,15 @@ class FlyDocsClient:
 
         result = relay.post("/issues", issue_input)
         issue = result.get("issue", result)
-        return {
+        response: dict = {
             "id": issue.get("id", ""),
             "identifier": issue.get("identifier", ""),
             "title": issue.get("title", kwargs.get("title", "")),
             "url": issue.get("url", ""),
         }
+        if auto_resolved:
+            response["autoResolved"] = auto_resolved
+        return response
 
     def transition(self, ref: str, status: str, comment: str) -> dict:
         if self.is_cloud:

package/template/.claude/skills/flydocs-workflow/scripts/issues.py

@@ -17,12 +17,68 @@ from flydocs_api import get_client, output_json, fail, resolve_text_input
 # ---------------------------------------------------------------------------
 
 def cmd_create(args: argparse.Namespace) -> None:
-    """Create a new issue."""
-    # Description resolution: --description-file > stdin > --description
+    """Create a new issue.
+
+    Enforces required fields to prevent incomplete issues:
+    - Description must be non-empty unless --triage is set
+    - Title is already required by argparse
+    - Type is already required by argparse
+
+    Auto-resolves from config when not explicitly passed:
+    - Category labels from issueLabels.category
+    - Repo labels from issueLabels.repo (multi-repo workspaces)
+    - Project from workspace.activeProjects
+    - Milestone from workspace.defaultMilestoneId
+    """
+    # Description resolution: --description-file > stdin > --description > --template
     description = resolve_text_input(file_arg=args.description_file)
     if description is None:
         description = args.description or ""
 
+    # Template fallback — read type template if no description provided
+    if not description.strip() and args.template:
+        template_path = Path(f".flydocs/templates/{args.type}.md")
+        if template_path.exists():
+            try:
+                raw = template_path.read_text()
+                # Strip agent instruction comments
+                import re as _re
+                description = _re.sub(r'<!--\s*AGENT:.*?-->\s*\n?', '', raw).strip()
+            except OSError:
+                pass
+
+    # Enforce non-empty description — triage bypasses with warning
+    if not description.strip():
+        if args.triage:
+            description = f"[Quick capture — needs refinement via /refine]\n\n{args.title}"
+            import sys as _sys
+            print(
+                "Note: Triage issue created with minimal description. "
+                "Run /refine to add full description and AC.",
+                file=_sys.stderr,
+            )
+        else:
+            template_path = f".flydocs/templates/{args.type}.md"
+            fail(
+                "Description is required when creating an issue. "
+                "Use --description, --description-file, or pipe to stdin.\n"
+                f"Read the template at {template_path} for the expected format, "
+                "then populate all sections before creating the issue."
+            )
+
+    # Auto-resolve assignee from me.json
+    assignee = args.assignee
+    if assignee in ("self", "me"):
+        me_file = Path(".flydocs/me.json")
+        if me_file.exists():
+            try:
+                me = json.loads(me_file.read_text())
+                assignee = me.get("providerId") or me.get("displayName")
+            except (json.JSONDecodeError, OSError):
+                fail("Could not read .flydocs/me.json — run: workspace.py get-me")
+        else:
+            fail("No .flydocs/me.json found — run: workspace.py get-me")
+
     client = get_client()
     result = client.create_issue(
         title=args.title,
@@ -30,8 +86,9 @@ def cmd_create(args: argparse.Namespace) -> None:
         description=description,
         priority=args.priority,
         estimate=args.estimate,
-        assignee=args.assignee,
+        assignee=assignee,
         project=args.project,
+        milestone=args.milestone,
         triage=args.triage,
     )
     output_json(result)
@@ -60,10 +117,51 @@ def cmd_list(args: argparse.Namespace) -> None:
     output_json(result)
 
 
+VALID_TRANSITIONS: dict[str, set[str]] = {
+    "BACKLOG": {"READY", "IMPLEMENTING", "CANCELED"},
+    "TRIAGE": {"BACKLOG", "READY", "IMPLEMENTING", "CANCELED"},
+    "READY": {"IMPLEMENTING", "CANCELED"},
+    "IMPLEMENTING": {"REVIEW", "BLOCKED", "CANCELED"},
+    "BLOCKED": {"IMPLEMENTING", "CANCELED"},
+    "REVIEW": {"COMPLETE", "TESTING", "IMPLEMENTING", "CANCELED"},
+    "TESTING": {"COMPLETE", "IMPLEMENTING", "CANCELED"},
+}
+
+
 def cmd_transition(args: argparse.Namespace) -> None:
-    """Transition an issue to a new status with a comment."""
+    """Transition an issue to a new status with a comment.
+
+    Validates:
+    - Comment is non-empty (not just whitespace)
+    - Transition is valid (from->to) based on current status
+    """
+    # Enforce non-empty comment
+    if not args.comment.strip():
+        fail(
+            "Transition comment cannot be empty. Every status transition "
+            "requires a meaningful comment describing what changed."
+        )
+
+    target = args.status.upper()
+
+    # Validate transition if we know the current status
+    status_file = Path(".flydocs/session/status")
+    if status_file.exists():
+        try:
+            current = status_file.read_text().strip().upper()
+            if current in VALID_TRANSITIONS:
+                allowed = VALID_TRANSITIONS[current]
+                if target not in allowed:
+                    allowed_str = ", ".join(sorted(allowed))
+                    fail(
+                        f"Invalid transition: {current} -> {target}. "
+                        f"Allowed targets from {current}: {allowed_str}"
+                    )
+        except OSError:
+            pass
+
     client = get_client()
-    result = client.transition(args.ref, args.status, args.comment)
+    result = client.transition(args.ref, target, args.comment)
     output_json(result)
 
 
@@ -357,6 +455,144 @@ def cmd_pr(args: argparse.Namespace) -> None:
         fail("PR creation timed out.")
 
 
+# ---------------------------------------------------------------------------
+# Audit
+# ---------------------------------------------------------------------------
+
+CHECKBOX_PATTERN = re.compile(r"^\s*-\s*\[[ x]\]", re.MULTILINE | re.IGNORECASE)
+
+
+def cmd_audit(args: argparse.Namespace) -> None:
+    """Audit issues for workflow compliance.
+
+    Checks for: missing descriptions, missing labels, missing AC checkboxes,
+    unassigned in-progress issues, and issues in wrong states.
+    """
+    client = get_client()
+    issues_data = client.list_issues(
+        status=args.status,
+        show_all=True,
+        limit=args.limit,
+    )
+
+    # Handle both list and dict response shapes
+    issues = issues_data if isinstance(issues_data, list) else issues_data.get("issues", [])
+
+    findings: list[dict] = []
+
+    for issue in issues:
+        ref = issue.get("identifier", "?")
+        title = issue.get("title", "")
+        status = issue.get("status", "").upper()
+        description = issue.get("description", "") or ""
+        assignee = issue.get("assignee")
+        labels = issue.get("labels", [])
+        priority = issue.get("priority")
+        issue_findings: list[str] = []
+
+        # Missing description
+        if not description.strip():
+            issue_findings.append("missing_description")
+
+        # Missing AC checkboxes (for non-idea types in active states)
+        if status in ("IMPLEMENTING", "REVIEW", "TESTING", "COMPLETE"):
+            if description and not CHECKBOX_PATTERN.search(description):
+                issue_findings.append("no_acceptance_criteria")
+
+        # Unassigned but in progress
+        if status in ("IMPLEMENTING", "REVIEW") and not assignee:
+            issue_findings.append("unassigned_active")
+
+        # Missing labels
+        if not labels:
+            issue_findings.append("no_labels")
+
+        # Default priority (might be intentional, but flag it)
+        if priority == 0 and status not in ("CANCELED",):
+            issue_findings.append("no_priority")
+
+        if issue_findings:
+            findings.append({
+                "ref": ref,
+                "title": title,
+                "status": status,
+                "findings": issue_findings,
+            })
+
+    output_json({
+        "total_checked": len(issues),
+        "issues_with_findings": len(findings),
+        "findings": findings,
+        "checks": [
+            "missing_description",
+            "no_acceptance_criteria",
+            "unassigned_active",
+            "no_labels",
+            "no_priority",
+        ],
+    })
+
+
+def cmd_fix(args: argparse.Namespace) -> None:
+    """Fix missing fields on an issue using config defaults.
+
+    Auto-applies: category labels from type, project from activeProjects,
+    milestone from defaultMilestoneId.
+    """
+    client = get_client()
+    issue = client.get_issue(args.ref, fields="full")
+    if not isinstance(issue, dict):
+        fail(f"Could not fetch issue {args.ref}")
+
+    fixes: dict = {}
+    applied: list[str] = []
+
+    # Fix missing labels (if we can detect type from title/description)
+    labels = issue.get("labels", [])
+    if not labels and client.is_cloud:
+        # Try to detect type from title keywords
+        title_lower = issue.get("title", "").lower()
+        detected_type = None
+        if any(w in title_lower for w in ["bug", "fix", "broken", "error"]):
+            detected_type = "bug"
+        elif any(w in title_lower for w in ["add", "implement", "create", "new"]):
+            detected_type = "feature"
+        elif any(w in title_lower for w in ["refactor", "clean", "update", "upgrade", "remove"]):
+            detected_type = "chore"
+        if detected_type:
+            cat_id = client.relay.get_category_label_id(detected_type)
+            if cat_id:
+                fixes["labels"] = cat_id
+                applied.append(f"label:{detected_type}")
+
+    # Fix missing project
+    project = issue.get("project")
+    if not project and client.is_cloud:
+        active = client.relay.workspace.get("activeProjects", [])
+        if active:
+            fixes["projectId"] = active[0]
+            applied.append("project:activeProjects")
+
+    # Fix missing milestone
+    milestone = issue.get("milestone")
+    if not milestone and client.is_cloud:
+        default_ms = client.relay.workspace.get("defaultMilestoneId")
+        if default_ms:
+            fixes["milestone"] = default_ms
+            applied.append("milestone:default")
+
+    if not fixes:
+        output_json({"ref": args.ref, "fixed": [], "message": "No fixes needed"})
+        return
+
+    result = client.update_issue(args.ref, **fixes)
+    output_json({
+        "ref": args.ref,
+        "fixed": applied,
+        "result": result,
+    })
+
+
 # ---------------------------------------------------------------------------
 # Argument parser
 # ---------------------------------------------------------------------------
@@ -373,9 +609,11 @@ def main() -> None:
     p.add_argument("--description-file", default=None)
     p.add_argument("--priority", type=int, default=3, choices=[0, 1, 2, 3, 4])
     p.add_argument("--estimate", type=int, default=None, choices=[0, 1, 2, 3, 5])
-    p.add_argument("--assignee", default=None)
+    p.add_argument("--assignee", default=None, help="Assignee name/ID, or 'self'/'me' for current user")
     p.add_argument("--project", default=None)
-    p.add_argument("--triage", action="store_true")
+    p.add_argument("--milestone", default=None, help="Milestone ID (defaults to workspace.defaultMilestoneId)")
+    p.add_argument("--template", action="store_true", help="Read type template as description skeleton")
+    p.add_argument("--triage", action="store_true", help="Quick capture — bypasses description enforcement")
 
     # -- get --
     p = sub.add_parser("get", help="Get a single issue")
@@ -464,6 +702,15 @@ def main() -> None:
     p.add_argument("--draft", action="store_true", help="Create as draft PR")
     p.add_argument("--dry-run", action="store_true", help="Show what would be created without creating")
 
+    # -- audit --
+    p = sub.add_parser("audit", help="Audit issues for workflow compliance")
+    p.add_argument("--status", default=None, help="Filter by status (default: all)")
+    p.add_argument("--limit", type=int, default=50, help="Max issues to check")
+
+    # -- fix --
+    p = sub.add_parser("fix", help="Fix missing fields on an issue using config defaults")
+    p.add_argument("ref")
+
     args = parser.parse_args()
 
     commands = {
@@ -481,6 +728,8 @@ def main() -> None:
         "assign-milestone": cmd_assign_milestone,
         "assign-cycle": cmd_assign_cycle,
         "pr": cmd_pr,
+        "audit": cmd_audit,
+        "fix": cmd_fix,
     }
     commands[args.command](args)