@cleocode/core 2026.3.45 → 2026.3.47

package/templates/git-hooks/commit-msg

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# commit-msg - CLEO task ID enforcement hook
+#
+# Validates commit messages contain T#### task references.
+# Checks task existence directly against .cleo/tasks.db (SQLite, canonical per ADR-006).
+#
+# Supports conventional commit scopes feat(T####): and suffix (T####) patterns.
+#
+# Installation: Automatically installed via `cleo init`
+# Manual: cp templates/git-hooks/commit-msg .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
+
+set -euo pipefail
+
+MSG_FILE="$1"
+COMMIT_MSG=$(cat "$MSG_FILE")
+
+# ============================================================================
+# BYPASS DETECTION
+# ============================================================================
+
+# Auto-bypass for automated commits (merges, reverts, CI/CD)
+if echo "$COMMIT_MSG" | grep -qE '^Merge (branch|pull request)'; then
+    exit 0
+fi
+
+if echo "$COMMIT_MSG" | grep -qE '^Revert '; then
+    exit 0
+fi
+
+if [[ -n "${CI:-}" || -n "${GITHUB_ACTIONS:-}" || -n "${GITLAB_CI:-}" ]]; then
+    exit 0
+fi
+
+# Auto-bypass for chore(cleo) checkpoints
+if echo "$COMMIT_MSG" | grep -qE '^chore\(cleo\)'; then
+    exit 0
+fi
+
+# Auto-bypass for release pipeline commits
+if echo "$COMMIT_MSG" | grep -qE '^release:|^chore\(release\):'; then
+    exit 0
+fi
+
+# ============================================================================
+# TASK ID EXTRACTION
+# Supports:
+#   1. Conventional commit scope: feat(T4541): description
+#   2. Parenthesized suffix: description (T4541)
+#   3. Bare reference: T4541 anywhere in message
+# ============================================================================
+
+TASK_ID=""
+
+# Pattern 1: Conventional commit scope - type(T####):
+if [[ -z "$TASK_ID" ]]; then
+    TASK_ID=$(echo "$COMMIT_MSG" | grep -oE '^[a-z]+\(T[0-9]+\)' | head -1 | grep -oE 'T[0-9]+' || true)
+fi
+
+# Pattern 2: Parenthesized suffix - (T####) anywhere in message
+if [[ -z "$TASK_ID" ]]; then
+    TASK_ID=$(echo "$COMMIT_MSG" | grep -oE '\(T[0-9]+\)' | head -1 | grep -oE 'T[0-9]+' || true)
+fi
+
+# Pattern 3: Bare T#### reference anywhere in message (fallback)
+if [[ -z "$TASK_ID" ]]; then
+    TASK_ID=$(echo "$COMMIT_MSG" | grep -oE '\bT[0-9]{3,}\b' | head -1 || true)
+fi
+
+# ============================================================================
+# VALIDATION
+# ============================================================================
+
+if [[ -z "$TASK_ID" ]]; then
+    echo "ERROR: No task ID in commit message"
+    echo ""
+    echo "Convention: Include T#### in commit message"
+    echo "Examples:"
+    echo "  feat(T2692): Add protocol checks"
+    echo "  fix(T1234): Resolve validation bug"
+    echo "  chore: Update deps (T5678)"
+    echo ""
+    echo "Bypass with: git commit --no-verify"
+    exit 1
+fi
+
+# ============================================================================
+# TASK EXISTENCE CHECK
+# Queries .cleo/tasks.db directly (SQLite, canonical storage per ADR-006).
+# Uses node:sqlite (Node 22+) as primary, sqlite3 CLI as fallback.
+# ============================================================================
+
+TASKS_DB=".cleo/tasks.db"
+
+if [[ ! -f "$TASKS_DB" ]]; then
+    echo "WARNING: $TASKS_DB not found, skipping task existence check"
+    echo "✓ Commit linked to $TASK_ID (unverified)"
+    exit 0
+fi
+
+validate_task() {
+    local task_id="$1"
+
+    # Primary: node:sqlite (available in Node 22+, same engine as CLEO core)
+    if command -v node &>/dev/null; then
+        local result
+        result=$(node -e "
+            try {
+                const { DatabaseSync } = require('node:sqlite');
+                const db = new DatabaseSync('$TASKS_DB', { open: true, readOnly: true });
+                const row = db.prepare('SELECT id FROM tasks WHERE id = ?').get('$task_id');
+                console.log(row ? 'found' : 'not_found');
+                db.close();
+            } catch { console.log('error'); }
+        " 2>/dev/null) || true
+        if [[ "$result" == "found" ]]; then
+            return 0
+        fi
+        if [[ "$result" == "not_found" ]]; then
+            return 1
+        fi
+    fi
+
+    # Fallback: sqlite3 CLI
+    if command -v sqlite3 &>/dev/null; then
+        local count
+        count=$(sqlite3 "$TASKS_DB" "SELECT COUNT(*) FROM tasks WHERE id = '$task_id';" 2>/dev/null) || true
+        if [[ "$count" -gt 0 ]] 2>/dev/null; then
+            return 0
+        fi
+        if [[ "$count" == "0" ]]; then
+            return 1
+        fi
+    fi
+
+    # No SQLite reader available — warn but allow
+    echo "WARNING: Cannot read $TASKS_DB (need node 22+ or sqlite3 CLI)"
+    return 0
+}
+
+if ! validate_task "$TASK_ID"; then
+    echo "ERROR: Task $TASK_ID not found in CLEO database"
+    echo ""
+    echo "Use: cleo find <query> to discover valid task IDs"
+    echo "Or bypass with: git commit --no-verify"
+    exit 1
+fi
+
+echo "✓ Commit linked to $TASK_ID"
+exit 0

package/templates/git-hooks/pre-commit

@@ -0,0 +1,40 @@
+#!/bin/sh
+# Pre-commit guardrails:
+#   1. Reject SQLite WAL/SHM files (data corruption risk).
+#   2. Block commits when core CLEO files are gitignored (data integrity).
+#
+# Installation: Automatically installed via `cleo init`
+
+set -e
+
+# ── 1. WAL/SHM/journal files ──────────────────────────────────────────
+BAD_FILES=$(git diff --cached --name-only | grep -E '\.(db-wal|db-shm|db-journal)$' || true)
+
+if [ -n "$BAD_FILES" ]; then
+  echo "ERROR: Refusing to commit SQLite WAL/SHM/journal files:"
+  echo "$BAD_FILES"
+  echo ""
+  echo "These are runtime files that must never be tracked in git."
+  echo "To fix: git rm --cached <file>"
+  exit 1
+fi
+
+# ── 2. Core file gitignore protection ─────────────────────────────────
+PROTECTED_FILES=".cleo/config.json .cleo/.gitignore .cleo/project-info.json .cleo/project-context.json"
+IGNORED_CORE=""
+
+for f in $PROTECTED_FILES; do
+  if [ -f "$f" ] && git check-ignore -q "$f" 2>/dev/null; then
+    IGNORED_CORE="$IGNORED_CORE $f"
+  fi
+done
+
+if [ -n "$IGNORED_CORE" ]; then
+  echo "ERROR: Critical CLEO files are being ignored by .gitignore:"
+  echo "$IGNORED_CORE"
+  echo ""
+  echo "These files MUST be tracked by git for CLEO data integrity."
+  echo "Check .gitignore and .cleo/.gitignore for rules ignoring these files."
+  echo "To fix: remove the ignore rule, then: git add <file>"
+  exit 1
+fi

package/templates/git-hooks/pre-push

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# pre-push - CalVer guard for release tags
+#
+# Blocks pushing tags that do not follow project CalVer policy:
+#   - Stable:     vYYYY.M.PATCH (current UTC month only)
+#   - Pre-release vYYYY.M.PATCH-suffix (current or next UTC month)
+#
+# Non-tag pushes are always allowed.
+
+set -euo pipefail
+
+current_year=$(date -u +%Y)
+current_month=$(date -u +%-m)
+next_month=$(( current_month == 12 ? 1 : current_month + 1 ))
+next_year=$(( current_month == 12 ? current_year + 1 : current_year ))
+
+is_valid_version_shape() {
+  local version="$1"
+  [[ "$version" =~ ^[0-9]{4}\.[0-9]{1,2}\.[0-9]+(-[A-Za-z0-9.]+)?$ ]]
+}
+
+validate_calver() {
+  local version="$1"
+
+  if ! is_valid_version_shape "$version"; then
+    echo "ERROR: Invalid CalVer format '$version'"
+    echo "Expected: YYYY.M.PATCH or YYYY.M.PATCH-suffix"
+    return 1
+  fi
+
+  local base="${version%%-*}"
+  local tag_year="${base%%.*}"
+  local rem="${base#*.}"
+  local tag_month="${rem%%.*}"
+
+  # Normalize month strings (e.g. "03" -> 3)
+  tag_month=$((10#$tag_month))
+
+  if [[ "$version" == *"-"* ]]; then
+    if [[ "$tag_year" != "$current_year" && "$tag_year" != "$next_year" ]] || \
+       [[ "$tag_month" != "$current_month" && "$tag_month" != "$next_month" ]]; then
+      echo "ERROR: Pre-release v$version outside allowed CalVer range"
+      echo "Allowed months: ${current_year}.${current_month} or ${next_year}.${next_month}"
+      return 1
+    fi
+  else
+    if [[ "$tag_year" != "$current_year" || "$tag_month" != "$current_month" ]]; then
+      echo "ERROR: Stable release v$version does not match current CalVer ${current_year}.${current_month}"
+      return 1
+    fi
+  fi
+
+  return 0
+}
+
+# Git passes refs to pre-push via stdin:
+# <local-ref> <local-sha> <remote-ref> <remote-sha>
+while read -r local_ref _ remote_ref _; do
+  tag_ref=""
+
+  if [[ "$remote_ref" == refs/tags/v* ]]; then
+    tag_ref="$remote_ref"
+  elif [[ "$local_ref" == refs/tags/v* ]]; then
+    tag_ref="$local_ref"
+  else
+    continue
+  fi
+
+  version="${tag_ref#refs/tags/v}"
+  if ! validate_calver "$version"; then
+    echo "Refusing push for tag: ${tag_ref#refs/tags/}"
+    echo "If intentional (e.g., backfill), push with: git push --no-verify"
+    exit 1
+  fi
+
+  echo "CalVer OK for tag ${tag_ref#refs/tags/}"
+done
+
+exit 0

package/templates/github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,143 @@
+name: Bug Report
+description: Report a bug or unexpected behavior in CLEO
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Bug Report
+
+        Thanks for reporting a bug! Please fill out the sections below so we can reproduce and fix it.
+
+        **If you're using an AI agent** (Claude Code, Cursor, etc.) to file this issue, the agent should run the diagnostic commands below and paste the output directly.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: |
+        Describe the bug clearly. What did you expect to happen vs what actually happened?
+      placeholder: |
+        When I ran `cleo add "My task"`, I expected a new task to be created, but instead I got an error...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: |
+        Provide the exact commands you ran, in order. Include the full command with all flags.
+      placeholder: |
+        1. `cleo init my-project`
+        2. `cleo session start --scope epic:T001 --auto-focus --name "test"`
+        3. `cleo add "Test task" --parent T001`
+        4. See error below
+    validations:
+      required: true
+
+  - type: textarea
+    id: error-output
+    attributes:
+      label: Error output
+      description: |
+        Paste the full error output. If CLEO returned JSON, paste the complete JSON response.
+        Use `cleo <command> 2>&1` to capture both stdout and stderr.
+      render: shell
+      placeholder: |
+        $ cleo add "Test task" --parent T001
+        {
+          "success": false,
+          "error": {
+            "code": "E_PARENT_NOT_FOUND",
+            "message": "Parent task T001 does not exist",
+            "exit": 10
+          }
+        }
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen instead?
+      placeholder: |
+        I expected the task to be created as a child of T001.
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Environment diagnostics
+      description: |
+        Run this command and paste the output:
+        ```bash
+        echo "--- CLEO Diagnostics ---" && echo "CLEO version: $(cleo version 2>/dev/null || echo 'not installed')" && echo "Node version: $(node --version 2>/dev/null || echo 'not found')" && echo "Install location: $(which cleo 2>/dev/null || echo 'not found')" && echo "OS: $(uname -srm 2>/dev/null || echo 'unknown')" && echo "Shell: $SHELL" && echo "Initialized: $(test -f .cleo/tasks.db && echo 'yes' || echo 'no')"
+        ```
+      render: shell
+      placeholder: |
+        --- CLEO Diagnostics ---
+        CLEO version: 2026.3.15
+        Node version: v24.0.0
+        Install location: /usr/local/bin/cleo
+        OS: Linux 6.5.0-44-generic x86_64
+        Shell: /bin/bash
+        Initialized: yes
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: Installation method
+      description: How did you install CLEO?
+      options:
+        - "npm install -g @cleocode/cleo"
+        - "npx @cleocode/cleo"
+        - "Built from source (cloned monorepo)"
+        - "Other (describe below)"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Severity
+      description: How much does this impact your workflow?
+      options:
+        - "Blocker - Cannot use CLEO at all"
+        - "Major - Core feature broken, no workaround"
+        - "Moderate - Feature broken but workaround exists"
+        - "Minor - Cosmetic or edge case"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: agent-usage
+    attributes:
+      label: Are you using an AI agent?
+      description: Are you (or your AI agent) filing this issue?
+      options:
+        - "Yes - AI agent filed this issue"
+        - "Yes - Human filing with AI agent assistance"
+        - "No - Filing manually"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: |
+        Any other details that might help. Examples:
+        - Contents of `.cleo/config.json` (if relevant)
+        - Output of `cleo doctor`
+        - Screenshots or screen recordings
+        - Related issues or PRs
+      placeholder: |
+        This started happening after I updated from 2026.2.x to 2026.3.x...
+    validations:
+      required: false

package/templates/github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://github.com/cleocode/cleo/tree/main/docs
+    about: Read the CLEO documentation before opening an issue
+  - name: Discussions
+    url: https://github.com/cleocode/cleo/discussions
+    about: Ask questions and share ideas in GitHub Discussions

package/templates/github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,125 @@
+name: Feature Request
+description: Suggest a new feature or improvement for CLEO
+title: "[Feature]: "
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Feature Request
+
+        Help us improve CLEO! Describe what you'd like to see added or changed.
+
+        **If you're using an AI agent** to submit this, provide as much context as possible about the use case and workflow.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or use case
+      description: |
+        What problem does this feature solve? Describe the situation where you need this.
+        Focus on the *problem*, not the solution.
+      placeholder: |
+        When working on a large project with 50+ tasks, I need to filter tasks by multiple
+        labels at once, but `cleo list` only supports filtering by a single label...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: |
+        How do you think this should work? Include example commands, expected output, or behavior.
+      placeholder: |
+        Add multi-label filtering to `cleo list`:
+        ```bash
+        cleo list --labels "bug,priority-high"
+        cleo list --labels "bug" --labels "priority-high"  # AND logic
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: |
+        Have you tried any workarounds? Are there other approaches that could solve this?
+      placeholder: |
+        Currently I pipe through jq manually:
+        ```bash
+        cleo list --json | jq '.[] | select(.labels | contains(["bug", "priority-high"]))'
+        ```
+        This works but is cumbersome and not discoverable for new users.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Feature area
+      description: Which part of CLEO does this relate to?
+      options:
+        - "Task management (add, update, complete, list)"
+        - "Session management (start, end, resume, scope)"
+        - "Hierarchy (epics, subtasks, dependencies)"
+        - "Search and filtering (find, list filters)"
+        - "Output and formatting (JSON, human-readable)"
+        - "Validation and data integrity"
+        - "Installation and setup"
+        - "MCP server integration"
+        - "Documentation"
+        - "AI agent workflow (skills, orchestrator, protocols)"
+        - "@cleocode/core package API"
+        - "Provider adapters (Claude Code, Cursor, OpenCode)"
+        - "Other"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      description: How big is this change?
+      options:
+        - "Small - Single command or flag addition"
+        - "Medium - Multiple components, moderate complexity"
+        - "Large - Cross-cutting change, new subsystem"
+        - "Not sure"
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Your environment (optional)
+      description: |
+        If this feature depends on your environment, run this and paste the output:
+        ```bash
+        echo "CLEO: $(cleo version 2>/dev/null || echo 'not installed')" && echo "Node: $(node --version)" && echo "OS: $(uname -srm)" && echo "Shell: $SHELL"
+        ```
+      render: shell
+    validations:
+      required: false
+
+  - type: dropdown
+    id: agent-usage
+    attributes:
+      label: Are you using an AI agent?
+      description: Are you (or your AI agent) filing this request?
+      options:
+        - "Yes - AI agent filed this request"
+        - "Yes - Human filing with AI agent assistance"
+        - "No - Filing manually"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: |
+        Links, screenshots, references to other tools that do this well, or anything else.
+    validations:
+      required: false

package/templates/github/ISSUE_TEMPLATE/help_question.yml

@@ -0,0 +1,99 @@
+name: Help / Question
+description: Ask for help using CLEO or understanding a feature
+title: "[Question]: "
+labels: ["question", "help"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Help / Question
+
+        Need help with CLEO? Ask here. No question is too basic.
+
+        **Before asking**, please check:
+        - [`cleo help`](https://github.com/cleocode/cleo) - Built-in help
+        - [Documentation](https://github.com/cleocode/cleo/tree/main/docs) - User guides
+        - [Existing issues](https://github.com/cleocode/cleo/issues?q=is%3Aissue+label%3Aquestion) - Someone may have asked already
+
+  - type: textarea
+    id: question
+    attributes:
+      label: What do you need help with?
+      description: |
+        Describe what you're trying to do and where you're stuck.
+      placeholder: |
+        I'm trying to set up CLEO for a new project, but I'm not sure how sessions
+        and scopes work together. When I run `cleo session start`, it asks for a scope...
+    validations:
+      required: true
+
+  - type: textarea
+    id: tried
+    attributes:
+      label: What have you tried?
+      description: |
+        What commands have you run or documentation have you read?
+      placeholder: |
+        I've tried:
+        1. `cleo help session`
+        2. Reading docs/guides/
+        3. Running `cleo session start --name "test"` but got an error about scope
+    validations:
+      required: true
+
+  - type: textarea
+    id: error-output
+    attributes:
+      label: Relevant output (if any)
+      description: |
+        If you're getting errors, paste the output here.
+      render: shell
+    validations:
+      required: false
+
+  - type: dropdown
+    id: topic
+    attributes:
+      label: Topic area
+      description: What area is your question about?
+      options:
+        - "Installation and setup"
+        - "Getting started / first use"
+        - "Task management (add, update, complete)"
+        - "Sessions and scopes"
+        - "Epics, subtasks, hierarchy"
+        - "Dependencies and blocking"
+        - "Search and filtering"
+        - "MCP server / AI agent integration"
+        - "Configuration"
+        - "Migration / upgrading"
+        - "@cleocode/core package API"
+        - "Provider adapters (Claude Code, Cursor, OpenCode)"
+        - "Other"
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Your environment
+      description: |
+        Run this command and paste the output:
+        ```bash
+        echo "CLEO: $(cleo version 2>/dev/null || echo 'not installed')" && echo "Node: $(node --version)" && echo "OS: $(uname -srm)" && echo "Shell: $SHELL"
+        ```
+      render: shell
+    validations:
+      required: false
+
+  - type: dropdown
+    id: agent-usage
+    attributes:
+      label: Are you using an AI agent?
+      description: Are you (or your AI agent) asking this question?
+      options:
+        - "Yes - AI agent filed this question"
+        - "Yes - Human filing with AI agent assistance"
+        - "No - Filing manually"
+    validations:
+      required: true