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

package/template/.claude/hooks/post-pr-check.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: post-pr-check.py
+Triggered: PostToolUse (Bash)
+Purpose: Warn when PRs are created without the standard template
+
+Detects direct `gh pr create` or `glab mr create` commands that bypass
+the `issues.py pr` dispatcher, and checks if the PR body contains
+required sections.
+
+Exit codes:
+  0 - Success (optional message output)
+  Non-zero - Non-blocking warning
+"""
+
+import json
+import re
+import sys
+
+
+REQUIRED_SECTIONS = ["## Summary", "## Test Plan"]
+
+PR_CREATE_PATTERNS = [
+    re.compile(r"^g(?:h)\s+pr\s+create"),
+    re.compile(r"^glab\s+mr\s+create"),
+]
+
+# Pattern for our own dispatcher — don't warn on these
+DISPATCHER_PATTERN = re.compile(
+    r"python3?\s+.*flydocs-workflow/scripts/issues\.py\s+pr"
+)
+
+
+def is_pr_create_command(command: str) -> bool:
+    """Check if command creates a PR/MR directly (not through dispatcher)."""
+    if DISPATCHER_PATTERN.search(command):
+        return False
+    return any(p.search(command) for p in PR_CREATE_PATTERNS)
+
+
+def extract_body(command: str) -> str | None:
+    """Try to extract PR body from command arguments."""
+    # Match --body "..." or --body '...'
+    match = re.search(r'--body\s+["\'](.+?)["\']', command, re.DOTALL)
+    if match:
+        return match.group(1)
+    # Match --body "$(cat <<'EOF' ... EOF)"  (heredoc pattern)
+    match = re.search(r"--body\s+\"\$\(cat\s+<<['\"]?EOF['\"]?\n(.+?)\nEOF", command, re.DOTALL)
+    if match:
+        return match.group(1)
+    # Match --description (GitLab)
+    match = re.search(r'--description\s+["\'](.+?)["\']', command, re.DOTALL)
+    if match:
+        return match.group(1)
+    return None
+
+
+def check_body(body: str) -> list[str]:
+    """Check if PR body contains required sections. Returns list of missing sections."""
+    missing = []
+    for section in REQUIRED_SECTIONS:
+        if section.lower() not in body.lower():
+            missing.append(section)
+    return missing
+
+
+def main() -> None:
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    if tool_name != "Bash":
+        sys.exit(0)
+
+    command = tool_input.get("command", "")
+
+    if not is_pr_create_command(command):
+        sys.exit(0)
+
+    # Check if body contains required sections
+    body = extract_body(command)
+
+    if body is None:
+        # No body found — PR was created without a body or with a file
+        print(
+            "[PR Template Notice] PR created without using `issues.py pr`. "
+            "For consistent PR descriptions with auto-populated issue context, "
+            "use: `python3 .claude/skills/flydocs-workflow/scripts/issues.py pr --issue <ref>`"
+        )
+        sys.exit(0)
+
+    missing = check_body(body)
+    if missing:
+        sections = ", ".join(missing)
+        print(
+            f"[PR Template Notice] PR body is missing required sections: {sections}. "
+            "Consider using `issues.py pr --issue <ref>` for standard template."
+        )
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/template/.claude/hooks/post-transition-check.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: post-transition-check.py
+Triggered: PostToolUse (Bash)
+Purpose: Validate that issue transitions include comments
+
+Fires after every Bash command. Only acts on `issues.py transition`
+commands. Warns when a transition is missing a comment argument and
+flags unusual state transitions.
+
+Exit codes:
+  0 - Always (non-blocking)
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+TRANSITION_PATTERN = re.compile(
+    r"issues\.py\s+transition\s+(\S+)\s+(\S+)(?:\s+(.+))?"
+)
+
+VALID_TRANSITIONS: dict[str, set[str]] = {
+    "BACKLOG": {"READY", "IMPLEMENTING", "CANCELED"},
+    "READY": {"IMPLEMENTING", "CANCELED"},
+    "IMPLEMENTING": {"REVIEW", "BLOCKED", "CANCELED"},
+    "BLOCKED": {"IMPLEMENTING", "CANCELED"},
+    "REVIEW": {"COMPLETE", "TESTING", "IMPLEMENTING", "CANCELED"},
+    "TESTING": {"COMPLETE", "IMPLEMENTING", "CANCELED"},
+}
+
+
+def read_current_status() -> str | None:
+    """Read current issue status from session file."""
+    try:
+        return Path(".flydocs/session/status").read_text().strip().upper()
+    except (OSError, ValueError):
+        return None
+
+
+def build_output(message: str) -> str:
+    return json.dumps({"hookSpecificOutput": {"additionalContext": message}})
+
+
+def main() -> None:
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        print("{}")
+        sys.exit(0)
+
+    if input_data.get("tool_name") != "Bash":
+        print("{}")
+        sys.exit(0)
+
+    command = input_data.get("tool_input", {}).get("command", "")
+    match = TRANSITION_PATTERN.search(command)
+
+    if not match:
+        print("{}")
+        sys.exit(0)
+
+    ref = match.group(1)
+    status = match.group(2).upper()
+    comment = match.group(3)
+
+    if not comment or not comment.strip():
+        msg = (
+            f"Transition to {status} is missing a comment. "
+            f"Every status transition requires a comment — add one now: "
+            f'python3 .claude/skills/flydocs-workflow/scripts/issues.py '
+            f'comment {ref} "<describe what changed>"'
+        )
+        print(build_output(msg))
+        sys.exit(0)
+
+    from_status = read_current_status()
+    if from_status and from_status in VALID_TRANSITIONS:
+        allowed = VALID_TRANSITIONS[from_status]
+        if status not in allowed:
+            msg = (
+                f"Unusual transition: {from_status} -> {status}. "
+                f"Verify this is intentional."
+            )
+            print(build_output(msg))
+            sys.exit(0)
+
+    print("{}")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/template/{.flydocs → .claude}/hooks/prompt-submit.py

@@ -101,6 +101,65 @@ def get_issue_context() -> tuple[str | None, str | None]:
     return issue_id, status
 
 
+def get_issue_context_line() -> str | None:
+    """Build a rich single-line issue context for prompt injection.
+
+    Consolidates issue ID, status, AC progress, and assignment into one
+    compact line that gives the agent full situational awareness.
+    """
+    issue_id, status = get_issue_context()
+    if not issue_id:
+        return None
+
+    parts = [issue_id]
+
+    # Status
+    status_display = {
+        'BACKLOG': 'Backlog',
+        'READY': 'Ready',
+        'IMPLEMENTING': 'In Progress',
+        'BLOCKED': 'Blocked',
+        'REVIEW': 'In Review',
+        'TESTING': 'QA',
+        'COMPLETE': 'Done',
+    }
+    if status:
+        parts.append(status_display.get(status, status))
+
+    # AC progress
+    ac_file = Path('.flydocs/session/acceptance-criteria.md')
+    if ac_file.exists():
+        try:
+            content = ac_file.read_text()
+            total = len(re.findall(r'^\s*-\s*\[', content, re.MULTILINE))
+            done = len(re.findall(r'^\s*-\s*\[x\]', content, re.MULTILINE | re.IGNORECASE))
+            if total > 0:
+                parts.append(f'AC {done}/{total}')
+        except (OSError, IOError):
+            pass
+
+    # Assignee from focus file
+    focus_file = Path('.flydocs/session/focus.md')
+    if focus_file.exists():
+        try:
+            content = focus_file.read_text()
+            assignee_match = re.search(r'[Aa]ssignee:\s*(.+)', content)
+            if assignee_match:
+                parts.append(f'Assigned: {assignee_match.group(1).strip()}')
+        except (OSError, IOError):
+            pass
+
+    # Workflow nudge based on status
+    if status == 'READY':
+        parts.append('[Transition to In Progress before starting work]')
+    elif status == 'IMPLEMENTING':
+        parts.append('[Update AC as you go, transition to Review when done]')
+    elif status == 'REVIEW':
+        parts.append('[Verify AC before approving]')
+
+    return f'Issue: {" | ".join(parts)}'
+
+
 def get_ac_progress() -> str | None:
     """Get acceptance criteria progress."""
     ac_file = Path('.flydocs/session/acceptance-criteria.md')
@@ -158,7 +217,24 @@ def get_orientation_context() -> str | None:
         except (json.JSONDecodeError, OSError, IOError):
             pass
 
-    # 2. Product context (first ~10 lines)
+    # 2. Topology and workspace orientation
+    config_file = Path('.flydocs/config.json')
+    if config_file.exists():
+        try:
+            config = json.loads(config_file.read_text())
+            topo = config.get('topology')
+            if topo:
+                topo_label = topo.get('label', '')
+                topo_type = topo.get('type', '')
+                siblings = topo.get('siblingRepos', [])
+                if topo_label == 'sibling-repos' and siblings:
+                    parts.append(f'Topology: {topo_label} ({len(siblings)} repos: {", ".join(siblings[:4])})')
+                elif topo_label in ('monorepo-multi', 'monorepo-single'):
+                    parts.append(f'Topology: {topo_label}')
+        except (json.JSONDecodeError, OSError, IOError):
+            pass
+
+    # 3. Product context (first ~10 lines)
     project_file = Path('flydocs/context/project.md')
     if project_file.exists():
         try:
@@ -178,6 +254,64 @@ def get_orientation_context() -> str | None:
     return ' | '.join(parts)
 
 
+def check_integrity_drift() -> str | None:
+    """Lightweight integrity drift check with 30-minute TTL.
+
+    Reads .flydocs/integrity.json and checks owned files/directories exist.
+    Caches result to avoid re-checking on every prompt.
+    """
+    integrity_file = Path('.flydocs/integrity.json')
+    if not integrity_file.exists():
+        return None
+
+    # TTL check — skip if checked within 30 minutes
+    cache_file = Path('.flydocs/integrity-cache.json')
+    if cache_file.exists():
+        try:
+            cache = json.loads(cache_file.read_text())
+            from datetime import datetime, timezone
+            cached_at = datetime.fromisoformat(cache.get('checkedAt', '').replace('Z', '+00:00'))
+            now = datetime.now(timezone.utc)
+            age_minutes = (now - cached_at).total_seconds() / 60
+            if age_minutes < 30:
+                # Return cached result if still fresh
+                missing = cache.get('missing', [])
+                if missing:
+                    return f'[Integrity drift: {len(missing)} owned file(s) missing — run /flydocs-update]'
+                return None
+        except (json.JSONDecodeError, OSError, ValueError, KeyError):
+            pass
+
+    # Run check
+    try:
+        data = json.loads(integrity_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    missing = []
+    for f in data.get('ownedFiles', []):
+        if not Path(f).exists():
+            missing.append(f)
+    for d in data.get('ownedDirectories', []):
+        if not Path(d).exists():
+            missing.append(d)
+
+    # Write cache
+    try:
+        from datetime import datetime, timezone
+        cache_data = {
+            'checkedAt': datetime.now(timezone.utc).isoformat(),
+            'missing': missing,
+        }
+        cache_file.write_text(json.dumps(cache_data))
+    except (OSError, IOError):
+        pass
+
+    if missing:
+        return f'[Integrity drift: {len(missing)} owned file(s) missing — run /flydocs-update]'
+    return None
+
+
 def get_flydocs_version() -> str | None:
     """Get FlyDocs version."""
     version_file = Path('.flydocs/version')
@@ -244,7 +378,7 @@ def get_config_freshness_nudge() -> str | None:
 
         cache_file = Path('.flydocs/validation-cache.json')
         if not cache_file.exists():
-            return '[Config not validated — run: python3 .claude/skills/flydocs-cloud/scripts/validate_setup.py]'
+            return '[Config not validated — run: python3 .claude/skills/flydocs-workflow/scripts/workspace.py validate]'
 
         from datetime import datetime, timezone
         cache = json.loads(cache_file.read_text())
@@ -258,7 +392,7 @@ def get_config_freshness_nudge() -> str | None:
         age_hours = (now - cached_at).total_seconds() / 3600
 
         if age_hours > 24:
-            return '[Config stale (>24h) — run: python3 .claude/skills/flydocs-cloud/scripts/validate_setup.py]'
+            return '[Config stale (>24h) — run: python3 .claude/skills/flydocs-workflow/scripts/workspace.py validate]'
     except (json.JSONDecodeError, OSError, IOError, ValueError):
         pass
     return None
@@ -312,30 +446,46 @@ def main() -> None:
         if branch_match:
             branch = branch_match.group(1).rstrip(',')
 
-    # Issue and status context
-    issue_id, status = get_issue_context()
-    if issue_id:
-        context_parts.append(f'Active issue: {issue_id}')
-    if status:
-        context_parts.append(f'Status: {status}')
-        reminder = get_workflow_reminder(status)
-        if reminder:
-            context_parts.append(reminder)
+    # Active project context
+    config_file = Path('.flydocs/config.json')
+    if config_file.exists():
+        try:
+            cfg = json.loads(config_file.read_text())
+            active_projects = cfg.get('workspace', {}).get('activeProjects', [])
+            if active_projects:
+                context_parts.append(f'ActiveProject: {active_projects[0]}')
+            elif cfg.get('tier') == 'cloud' and cfg.get('setupComplete'):
+                context_parts.append('[No active project set — run workspace.py set-active-project]')
+        except (json.JSONDecodeError, OSError, IOError):
+            pass
 
-    # AC progress
-    ac_progress = get_ac_progress()
-    if ac_progress:
-        context_parts.append(ac_progress)
+    # Rich issue context (consolidated: ID, status, AC, assignment, nudge)
+    issue_line = get_issue_context_line()
+    if issue_line:
+        context_parts.append(issue_line)
 
-    # Setup completion nudge OR config freshness nudge (mutually exclusive)
+    # Setup completion nudge OR onboard nudge OR config freshness nudge
     setup_nudge = get_setup_nudge()
     if setup_nudge:
         context_parts.append(setup_nudge)
     else:
+        # Check if onboarding has been completed
+        try:
+            config_data = json.loads(Path('.flydocs/config.json').read_text())
+            if config_data.get('setupComplete') and not config_data.get('onboardComplete'):
+                context_parts.append('[Run /onboard to get oriented to this project]')
+        except (json.JSONDecodeError, OSError, IOError):
+            pass
+
         freshness_nudge = get_config_freshness_nudge()
         if freshness_nudge:
             context_parts.append(freshness_nudge)
 
+    # Integrity drift check (TTL-cached, runs at most every 30 min)
+    drift = check_integrity_drift()
+    if drift:
+        context_parts.append(drift)
+
     # FlyDocs version
     version = get_flydocs_version()
     if version:

package/template/.claude/hooks/session-start.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: session-start.py
+Triggered: When a new Claude Code session begins (SessionStart)
+Purpose: Inject continuity context from previous session, active issue, and config state
+
+Exit codes:
+  0 - Success (JSON output with additionalContext)
+"""
+
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def get_previous_session_summary() -> str | None:
+    """Extract key details from last session summary."""
+    summary_file = Path('.flydocs/session/last-summary.json')
+    if not summary_file.exists():
+        return None
+    try:
+        data = json.loads(summary_file.read_text())
+        bits: list[str] = []
+        issues = data.get('issues', [])
+        if issues:
+            bits.append(f'issues={",".join(issues)}')
+        pending = data.get('pending', [])
+        if pending:
+            bits.append(f'pending={len(pending)}')
+        blockers = data.get('blockers', [])
+        if blockers:
+            bits.append(f'blockers={len(blockers)}')
+        notes = data.get('notes')
+        if notes:
+            bits.append(f'notes={notes[:80]}')
+        if bits:
+            return f'Last session: {" | ".join(bits)}'
+    except (json.JSONDecodeError, OSError, IOError):
+        pass
+    return None
+
+
+def get_active_issue_context() -> str | None:
+    """Build active issue status line from session files."""
+    issue_id = None
+    status = None
+
+    focus_file = Path('.flydocs/session/focus.md')
+    if focus_file.exists():
+        try:
+            match = re.search(r'[A-Z]+-[0-9]+', focus_file.read_text())
+            if match:
+                issue_id = match.group(0)
+        except (OSError, IOError):
+            pass
+
+    status_file = Path('.flydocs/session/status')
+    if status_file.exists():
+        try:
+            status = status_file.read_text().strip()
+        except (OSError, IOError):
+            pass
+
+    if not issue_id:
+        return None
+
+    ac_part = ''
+    ac_file = Path('.flydocs/session/acceptance-criteria.md')
+    if ac_file.exists():
+        try:
+            content = ac_file.read_text()
+            total = len(re.findall(r'^\s*-\s*\[', content, re.MULTILINE))
+            done = len(re.findall(r'^\s*-\s*\[x\]', content, re.MULTILINE | re.IGNORECASE))
+            if total > 0:
+                ac_part = f' | AC: {done}/{total}'
+        except (OSError, IOError):
+            pass
+
+    status_label = f' ({status})' if status else ''
+    return f'Active: {issue_id}{status_label}{ac_part}'
+
+
+def get_config_freshness() -> str | None:
+    """Warn if validation cache is stale or missing."""
+    cache_file = Path('.flydocs/validation-cache.json')
+    if not cache_file.exists():
+        return None
+    try:
+        data = json.loads(cache_file.read_text())
+        timestamp_str = data.get('timestamp')
+        if not timestamp_str:
+            return None
+        cached_at = datetime.fromisoformat(timestamp_str.replace('Z', '+00:00'))
+        age_hours = (datetime.now(timezone.utc) - cached_at).total_seconds() / 3600
+        if age_hours > 24:
+            return 'Config validation stale (>24h) — consider running: python3 .claude/skills/flydocs-workflow/scripts/workspace.py validate'
+    except (json.JSONDecodeError, OSError, IOError, ValueError):
+        pass
+    return None
+
+
+def main() -> None:
+    """Main hook execution."""
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        input_data = {}
+
+    cwd = input_data.get('cwd', '')
+    if cwd and Path(cwd).is_dir():
+        os.chdir(cwd)
+    elif os.environ.get('CLAUDE_PROJECT_DIR') and Path(os.environ['CLAUDE_PROJECT_DIR']).is_dir():
+        os.chdir(os.environ['CLAUDE_PROJECT_DIR'])
+
+    parts: list[str] = []
+
+    summary = get_previous_session_summary()
+    if summary:
+        parts.append(summary)
+
+    issue_ctx = get_active_issue_context()
+    if issue_ctx:
+        parts.append(issue_ctx)
+
+    freshness = get_config_freshness()
+    if freshness:
+        parts.append(freshness)
+
+    if not parts:
+        print('{}')
+        sys.exit(0)
+
+    output = {
+        "hookSpecificOutput": {
+            "additionalContext": " | ".join(parts)
+        }
+    }
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""
+FlyDocs Hook: stop-gate.py
+Triggered: Stop (every time the agent finishes responding)
+Purpose: Gate agent completion on workflow state — blocks finish if issue
+         is still In Progress, warns if acceptance criteria are incomplete.
+
+Exit codes:
+  0 - Allow stop (optional JSON output parsed)
+  2 - Block stop (stderr shown to Claude as instruction)
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+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)
+
+
+def read_file_safe(path):
+    """Read file contents, returning None on any error."""
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except (OSError, ValueError):
+        return None
+
+
+def extract_issue_id(text):
+    """Extract first issue ID matching PROJ-123 pattern."""
+    match = ISSUE_ID_PATTERN.search(text)
+    return match.group(0) if match else None
+
+
+def main():
+    # -- Parse stdin --
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        input_data = {}
+
+    # -- Loop guard: if the hook itself triggered this stop, exit cleanly --
+    if input_data.get("stop_hook_active"):
+        sys.exit(0)
+
+    # -- Resolve working directory --
+    cwd = input_data.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR", "")
+    if not cwd:
+        sys.exit(0)
+
+    try:
+        os.chdir(cwd)
+    except OSError:
+        sys.exit(0)
+
+    session_dir = Path(".flydocs/session")
+
+    # -- Check for active focus --
+    focus_text = read_file_safe(session_dir / "focus.md")
+    if not focus_text:
+        sys.exit(0)
+
+    issue_id = extract_issue_id(focus_text)
+    if not issue_id:
+        sys.exit(0)
+
+    # -- Read current status --
+    status_text = read_file_safe(session_dir / "status")
+    if not status_text:
+        sys.exit(0)
+
+    status = status_text.strip().upper()
+
+    # -- IMPLEMENTING: block completion --
+    if status == "IMPLEMENTING":
+        msg = (
+            "Issue {} is still In Progress. "
+            "Transition to Review before finishing:\n"
+            "  python3 .claude/skills/flydocs-workflow/scripts/issues.py "
+            "transition {} REVIEW \"Implementation complete\""
+        ).format(issue_id, issue_id)
+        sys.stderr.write(msg)
+        sys.exit(2)
+
+    # -- REVIEW: warn 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))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()