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

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

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""Tests for workflow enforcement logic.
+
+Run: python3 test_enforcement.py
+Tests the enforcement functions in issues.py, auto-approve.py, stop-gate.py,
+and post-transition-check.py without requiring API access.
+"""
+
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+# Add parent dirs to path for imports
+SCRIPT_DIR = Path(__file__).parent.resolve()
+HOOKS_DIR = SCRIPT_DIR.parent.parent.parent / "hooks"
+sys.path.insert(0, str(SCRIPT_DIR))
+sys.path.insert(0, str(HOOKS_DIR))
+
+passed = 0
+failed = 0
+
+
+def test(name: str):
+    """Decorator to register and run a test."""
+    def decorator(fn):
+        global passed, failed
+        try:
+            fn()
+            print(f"  PASS: {name}")
+            passed += 1
+        except AssertionError as e:
+            print(f"  FAIL: {name} — {e}")
+            failed += 1
+        except Exception as e:
+            print(f"  ERROR: {name} — {type(e).__name__}: {e}")
+            failed += 1
+        return fn
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# issues.py enforcement tests
+# ---------------------------------------------------------------------------
+
+print("\n## issues.py enforcement")
+
+
+@test("create rejects empty description")
+def _():
+    """issues.py create should fail with empty --description."""
+    import subprocess
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT_DIR / "issues.py"), "create",
+         "--title", "Test", "--type", "feature", "--description", ""],
+        capture_output=True, text=True, timeout=10,
+    )
+    assert result.returncode != 0, f"Expected failure, got rc={result.returncode}"
+    assert "Description is required" in result.stderr, f"Expected error message, got: {result.stderr[:200]}"
+
+
+@test("create rejects missing description")
+def _():
+    """issues.py create should fail without --description flag."""
+    import subprocess
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT_DIR / "issues.py"), "create",
+         "--title", "Test", "--type", "feature"],
+        capture_output=True, text=True, timeout=10,
+    )
+    assert result.returncode != 0, f"Expected failure, got rc={result.returncode}"
+
+
+@test("create allows --triage without description")
+def _():
+    """issues.py create with --triage should not fail on empty description."""
+    # This would succeed only if we have API access, so just check the
+    # enforcement bypass by testing the error message doesn't say "Description is required"
+    import subprocess
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT_DIR / "issues.py"), "create",
+         "--title", "Quick test", "--type", "bug", "--triage"],
+        capture_output=True, text=True, timeout=10,
+    )
+    # It may fail for other reasons (no API), but NOT for missing description
+    assert "Description is required" not in result.stderr, \
+        f"--triage should bypass description check, got: {result.stderr[:200]}"
+
+
+@test("transition rejects empty comment")
+def _():
+    """issues.py transition should reject whitespace-only comment."""
+    import subprocess
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT_DIR / "issues.py"), "transition",
+         "FLY-999", "REVIEW", "   "],
+        capture_output=True, text=True, timeout=10,
+    )
+    assert result.returncode != 0, f"Expected failure, got rc={result.returncode}"
+    assert "comment cannot be empty" in result.stderr, f"Got: {result.stderr[:200]}"
+
+
+# ---------------------------------------------------------------------------
+# auto-approve.py enforcement tests
+# ---------------------------------------------------------------------------
+
+print("\n## auto-approve.py enforcement")
+
+
+@test("should_approve matches workflow scripts")
+def _():
+    # Import the function directly
+    sys.path.insert(0, str(HOOKS_DIR))
+    # We need to import carefully since it's a hook script
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("auto_approve", HOOKS_DIR / "auto-approve.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    assert mod.should_approve("python3 .claude/skills/flydocs-workflow/scripts/issues.py create --title test")
+    assert mod.should_approve("python3 .claude/skills/flydocs-workflow/scripts/workspace.py validate")
+    assert not mod.should_approve("python3 malicious.py")
+    assert not mod.should_approve("rm -rf /")
+
+
+@test("validate_create_args warns on missing description")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("auto_approve", HOOKS_DIR / "auto-approve.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    warnings = mod.validate_create_args(
+        'python3 .claude/skills/flydocs-workflow/scripts/issues.py create --title "test" --type feature'
+    )
+    assert len(warnings) > 0, "Should warn about missing --description"
+    assert any("description" in w.lower() for w in warnings)
+
+
+@test("validate_create_args no warning when description present")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("auto_approve", HOOKS_DIR / "auto-approve.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    warnings = mod.validate_create_args(
+        'python3 .claude/skills/flydocs-workflow/scripts/issues.py create --title "test" --type feature --description "Full description here with enough content"'
+    )
+    desc_warnings = [w for w in warnings if "Missing --description" in w]
+    assert len(desc_warnings) == 0, f"Should not warn when description present, got: {warnings}"
+
+
+@test("get_transition_comment_hint returns template for known status")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("auto_approve", HOOKS_DIR / "auto-approve.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    hint = mod.get_transition_comment_hint("issues.py transition FLY-123 IMPLEMENTING")
+    assert hint is not None, "Should return hint for IMPLEMENTING"
+    assert "Starting implementation" in hint
+
+
+@test("get_transition_comment_hint returns None for non-transition")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("auto_approve", HOOKS_DIR / "auto-approve.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    hint = mod.get_transition_comment_hint("issues.py list --status BACKLOG")
+    assert hint is None, "Should return None for non-transition commands"
+
+
+# ---------------------------------------------------------------------------
+# Transition validation tests
+# ---------------------------------------------------------------------------
+
+print("\n## Transition validation")
+
+
+@test("VALID_TRANSITIONS allows IMPLEMENTING -> REVIEW")
+def _():
+    # Test the transition map directly from issues.py
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("issues", SCRIPT_DIR / "issues.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    assert "REVIEW" in mod.VALID_TRANSITIONS["IMPLEMENTING"]
+    assert "BLOCKED" in mod.VALID_TRANSITIONS["IMPLEMENTING"]
+
+
+@test("VALID_TRANSITIONS blocks BACKLOG -> REVIEW")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("issues", SCRIPT_DIR / "issues.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    assert "REVIEW" not in mod.VALID_TRANSITIONS["BACKLOG"]
+
+
+@test("VALID_TRANSITIONS blocks READY -> REVIEW")
+def _():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("issues", SCRIPT_DIR / "issues.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    assert "REVIEW" not in mod.VALID_TRANSITIONS["READY"]
+
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+
+print(f"\n{'='*50}")
+print(f"Results: {passed} passed, {failed} failed, {passed + failed} total")
+if failed > 0:
+    sys.exit(1)

package/template/.claude/skills/flydocs-workflow/session.md

@@ -4,7 +4,17 @@
 
 When a conversation begins or the user returns after a gap:
 
-1. **Query graph for issue context** (if an issue ID is known from the prompt or last session) —
+1. **Verify config completeness** — Read `.flydocs/config.json` and check:
+   - `workspace.activeProjects` is non-empty (cloud tier) — warn if missing
+   - `workspace.defaultMilestoneId` is set — warn if null
+   - `issueLabels.category` has non-null values — warn if unconfigured
+     These are informational warnings, not blocking. Example:
+
+   ```
+   Config check: activeProjects OK | milestone OK | labels: 2 of 4 configured (idea, chore missing)
+   ```
+
+2. **Query graph for issue context** (if an issue ID is known from the prompt or last session) —
 
    ```
    python3 .claude/skills/flydocs-workflow/scripts/graph_query.py --node <issue-id> --depth 2
@@ -13,28 +23,28 @@ When a conversation begins or the user returns after a gap:
    This surfaces related decisions, blocking relationships, and recent session activity.
    Skip silently if the script is not installed or the graph has not been built.
 
-2. **Check workspace context** — If `flydocs/context/service.json` exists, note the
+3. **Check workspace context** — If `flydocs/context/service.json` exists, note the
    repo's topology and dependencies. For multi-repo workspaces (topology type 3 or 4),
    briefly mention which sibling repos exist and any active cross-repo dependencies.
    This helps the user orient when switching between repos.
 
-3. **Fetch all product issues in one call** — Run `issues.py list --active --limit 100`.
+4. **Fetch all product issues in one call** — Run `issues.py list --active --limit 100`.
    This is auto-scoped by the product cascade: `activeProjects` → `product.labelIds` → team-wide.
    Issues outside the product scope are never shown.
 
-4. **Identify the active project** — Read `workspace.activeProjects` from config.
+5. **Identify the active project** — Read `workspace.activeProjects` from config.
    Separate issues into two buckets:
    - **Active project issues** — issues whose `projectId` matches an active project
    - **Other product issues** — issues in the product scope but in a different project
 
-5. **Group active project issues by milestone** — Use the `milestone` and `milestoneSortOrder`
+6. **Group active project issues by milestone** — Use the `milestone` and `milestoneSortOrder`
    fields returned by the script. Sort milestones by `milestoneSortOrder` (lowest first = earliest).
    Within each milestone, group by status.
 
-6. **Identify the current milestone** — The first milestone (by sort order) that still has
+7. **Identify the current milestone** — The first milestone (by sort order) that still has
    open issues. This is where work should focus.
 
-7. **Present the dashboard:**
+8. **Present the dashboard:**
 
    ```
    Welcome back! [Product Name] status:
@@ -57,21 +67,21 @@ When a conversation begins or the user returns after a gap:
    Suggested starting point: [ISSUE-ID] — [reason: highest priority in current milestone / unblocks others / due soon]
    ```
 
-8. **Suggest where to start** — Use this priority cascade:
+9. **Suggest where to start** — Use this priority cascade:
    - Blocked issues that need unblocking (always surface first)
    - In-progress issues (continue existing work)
    - Due date approaching (within 7 days)
    - Highest priority in the current milestone
    - Issues that unblock downstream milestones
 
-9. **Surface other product issues briefly** — If there are issues in the product scope
-   but outside the active project, mention the count with a one-line summary:
+10. **Surface other product issues briefly** — If there are issues in the product scope
+    but outside the active project, mention the count with a one-line summary:
 
-   ```
-   Also in [Product Name]: [N] issues across other projects (use --all to see)
-   ```
+    ```
+    Also in [Product Name]: [N] issues across other projects (use --all to see)
+    ```
 
-10. **Check for stale issues** — Flag issues exceeding staleness thresholds (see below).
+11. **Check for stale issues** — Flag issues exceeding staleness thresholds (see below).
 
 **Important:** Do NOT make separate API calls per status or per milestone. One call returns
 all issues with their status and milestone fields — group them in your response.
@@ -109,7 +119,17 @@ When the user indicates they're done for the session:
    Populate from the session data gathered in step 1. Use the Write tool or a script — the file
    must exist on disk so the prompt hook can read it on the next session start.
 
-7. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
+7. **Audit session issues** — Run `issues.py audit --limit 20` to check all recently
+   touched issues for compliance. Report findings as part of the wrap summary:
+
+   ```
+   Session audit: 5 issues checked, 1 finding
+   - FLY-484: missing_description
+   ```
+
+   This is informational — don't block the wrap, just surface gaps.
+
+8. **Record session in context graph** — Call `graph_session.py` with summary and issues worked on:
    ```
    python3 .claude/skills/flydocs-workflow/scripts/graph_session.py \
        --summary "Brief summary of session outcomes" \
@@ -117,8 +137,8 @@ When the user indicates they're done for the session:
        [--decision NNN]
    ```
    This creates a session node for cross-session continuity. Skip silently if the script is not installed.
-8. **Verify** — Confirm the project update was posted (update ID returned).
-9. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
+9. **Verify** — Confirm the project update was posted (update ID returned).
+10. **Ask about uncommitted changes** — If git shows uncommitted work, offer to commit.
 
 Do not just summarize in chat. Actually post the update. Do not skip if the user seems in a hurry.
 

package/template/.flydocs/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.20",
+  "version": "0.6.0-alpha.22",
   "sourceRepo": "github.com/plastrlab/flydocs-core",
   "tier": "local",
   "setupComplete": false,

package/template/.flydocs/templates/bug.md

@@ -0,0 +1,30 @@
+<!-- AGENT: Use this template when creating bug issues. Fill all [bracketed] sections. -->
+
+## What
+
+[One sentence describing the bug]
+
+## Expected Behavior
+
+[What should happen]
+
+## Actual Behavior
+
+[What actually happens]
+
+## Steps to Reproduce
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Acceptance Criteria
+
+- [ ] Bug is fixed and original behavior restored
+- [ ] [Additional verification criteria]
+
+## Context
+
+- **Frequency:** [Always / Sometimes / Rare]
+- **Impact:** [Blocking / Degraded / Cosmetic]
+- **Environment:** [Where it occurs — browser, OS, tier]

package/template/.flydocs/templates/chore.md

@@ -0,0 +1,22 @@
+<!-- AGENT: Use this template when creating chore issues. Fill all [bracketed] sections. -->
+
+## What
+
+[One sentence describing the task]
+
+## Why
+
+[Why this maintenance/cleanup is needed now]
+
+## Acceptance Criteria
+
+- [ ] [Specific, testable criterion 1]
+- [ ] [Specific, testable criterion 2]
+
+## Scope
+
+[What's included and what's explicitly excluded]
+
+## Technical Notes
+
+[Approach, risks, or migration steps — remove if not applicable]

package/template/.flydocs/templates/feature.md

@@ -0,0 +1,27 @@
+<!-- AGENT: Use this template when creating feature issues. Fill all [bracketed] sections. -->
+
+## What
+
+[One sentence describing the feature]
+
+## Why
+
+[Problem this solves or opportunity it creates]
+
+## User Story
+
+As a [role], I want to [action] so that [benefit].
+
+## Acceptance Criteria
+
+- [ ] [Specific, testable criterion 1]
+- [ ] [Specific, testable criterion 2]
+- [ ] [Specific, testable criterion 3]
+
+## Technical Notes
+
+[Implementation approach, constraints, or dependencies — remove if not applicable]
+
+## Out of Scope
+
+[Explicitly list what this does NOT include — remove if not applicable]

package/template/.flydocs/templates/idea.md

@@ -0,0 +1,22 @@
+<!-- AGENT: Use this template when creating idea issues. Fill all [bracketed] sections. -->
+
+## What
+
+[One sentence describing the idea]
+
+## Why
+
+[Problem or opportunity this addresses]
+
+## Rough Shape
+
+[Initial thinking on approach — does not need to be detailed]
+
+## Open Questions
+
+- [Question 1]
+- [Question 2]
+
+## Next Steps
+
+- [ ] [First step to explore or validate this idea]

package/template/.flydocs/version

@@ -1 +1 @@
-0.6.0-alpha.20
+0.6.0-alpha.22

package/template/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0-alpha.20",
+  "version": "0.6.0-alpha.22",
   "description": "FlyDocs Core - Manifest of all managed files",
   "repository": "github.com/plastrlab/flydocs-core",