# =============================================================================
# parpour — Root Taskfile
# =============================================================================
# Specification and planning workspace driving civ (Rust sim) and venture
# (agent platform). Spec-first workflow with governance enforcement.
# Run `task --list` to see all available tasks.
# =============================================================================

version: '3'

vars:
  DOCS_DIR: docs
  VENTURE_DIR: venture

tasks:
  default:
    cmds:
      - task --list
    silent: true

  # -- Specification Validation --

  spec:validate:
    desc: Validate all specifications for completeness and consistency
    cmds:
      - |
        echo "Validating specifications..."
        bash scripts/spec-validate.sh || exit 1
    sources:
      - "*_SPEC.md"
      - "TRACK_*.md"
      - "*.md"

  spec:index:
    desc: Build master specification index; check coverage and links
    cmds:
      - |
        echo "Indexing specifications..."
        bash scripts/spec-index.sh || exit 1
    sources:
      - "*_SPEC.md"
      - "TRACK_*.md"
      - NEXT_STEPS.md
      - SPECS_INDEX.md

  spec:gaps:
    desc: Find specification gaps and untraced requirements
    cmds:
      - |
        echo "Checking for spec gaps..."
        bash scripts/spec-gaps.sh || exit 1
    sources:
      - "*_SPEC.md"
      - "TRACK_*.md"
      - NEXT_STEPS.md

  # -- Project Health Checks --

  venture:check:
    desc: Verify venture specs are linked to NEXT_STEPS.md
    cmds:
      - |
        echo "Checking venture spec links..."
        bash scripts/venture-check.sh || exit 1
    sources:
      - "*_SPEC.md"
      - "TRACK_*.md"
      - NEXT_STEPS.md

  civ:check:
    desc: Verify CIV specs are complete and linked
    cmds:
      - |
        echo "Checking CIV spec status..."
        bash scripts/civ-check.sh || exit 1
    sources:
      - NEXT_STEPS.md
      - SPECS_INDEX.md

  # -- Traceability Tasks --

  traceability:check:
    desc: Check spec-to-implementation traceability
    cmds:
      - |
        echo "=== Traceability Check ==="
        echo "Checking for traceability matrix updates..."
        ls -1 docs/traceability/TRACEABILITY_MATRIX.md docs/traceability/VENTURE_TRACEABILITY_MATRIX.md 2>/dev/null || echo "Create with task traceability:build-matrix"
    sources:
      - "*.md"
      - docs/traceability/

  traceability:build-matrix:
    desc: Generate or update traceability matrices from specs
    cmds:
      - |
        echo "=== Building Traceability Matrices ==="
        mkdir -p {{.DOCS_DIR}}/traceability
        echo "Traceability matrices in: {{.DOCS_DIR}}/traceability/"
        ls -1 {{.DOCS_DIR}}/traceability/*.md 2>/dev/null || echo "No matrices yet"

  # -- Governance Tasks --

  governance:setup:
    desc: Create governance documentation structure
    cmds:
      - |
        echo "=== Setting up Governance Structure ==="
        mkdir -p {{.DOCS_DIR}}/governance
        mkdir -p {{.DOCS_DIR}}/adr
        mkdir -p {{.DOCS_DIR}}/research
        mkdir -p {{.DOCS_DIR}}/traceability
        echo "Created directories:"
        ls -d {{.DOCS_DIR}}/*/ 2>/dev/null || true
        echo "=== Governance structure ready ==="

  docs:list:
    desc: List all documentation files and their status
    cmds:
      - |
        echo "=== Documentation Files ==="
        echo ""
        echo "Root-level specs:"
        ls -1 *.md 2>/dev/null | grep -E "(TECHNICAL|TRACK|ARTIFACT|API|DATA|OPS|USER|PRODUCT|SCHEMA|ROLE|IMPLEMENTATION)" | xargs -I {} echo "  • {}" || echo "  (none)"
        echo ""
        echo "Governance docs:"
        ls -1 {{.DOCS_DIR}}/governance/*.md 2>/dev/null | xargs -I {} basename {} | xargs -I {} echo "  • {}" || echo "  (none)"
        echo ""
        echo "Architecture Decision Records (ADRs):"
        ls -1 {{.DOCS_DIR}}/adr/*.md 2>/dev/null | xargs -I {} basename {} | xargs -I {} echo "  • {}" || echo "  (none)"
        echo ""
        echo "Traceability:"
        ls -1 {{.DOCS_DIR}}/traceability/*.md 2>/dev/null | xargs -I {} basename {} | xargs -I {} echo "  • {}" || echo "  (none)"
        echo ""
        echo "=== Documentation listing complete ==="

  # -- Markdown Linting --

  lint:markdown:
    desc: Lint all markdown files
    cmds:
      - |
        if command -v markdownlint-cli2 >/dev/null 2>&1; then
          markdownlint-cli2 "**/*.md" || true
        else
          echo "markdownlint-cli2 not installed. Install with: npm install -g markdownlint-cli2"
        fi
    sources:
      - "**/*.md"

  # -- Quality Gates --

  quality:fast:
    desc: Run fast teammate-safe quality checks (spec validation + markdown lint)
    cmds:
      - task spec:validate
      - task lint:markdown
    silent: false

  quality:
    desc: Run full strict quality checks (all spec checks + linting + gates)
    cmds:
      - task spec:validate
      - task spec:index
      - task spec:gaps
      - task venture:check
      - task civ:check
      - task lint:markdown
      - task gate
    silent: false

  gate:
    desc: Run full quality gate system
    cmds:
      - bash scripts/quality/quality-gate.sh

  # -- Documentation --

  docs:build:
    desc: Build VitePress documentation site
    cmds:
      - |
        if command -v npm >/dev/null 2>&1; then
          cd docs && npm run docs:build
        else
          echo "npm not installed. Install Node.js to build docs."
        fi

  docs:dev:
    desc: Run VitePress documentation dev server
    cmds:
      - |
        if command -v npm >/dev/null 2>&1; then
          cd docs && npx vitepress dev
        else
          echo "npm not installed. Install Node.js to run dev server."
        fi

  # -- Hooks Management --

  hooks:install:
    desc: Install pre-commit hooks
    cmds:
      - |
        if command -v pre-commit >/dev/null 2>&1; then
          pre-commit install
        else
          echo "pre-commit not installed. Install with: pip install pre-commit"
        fi

  pre-commit:install:
    desc: Install pre-commit hooks (alias for hooks:install)
    cmds:
      - task hooks:install

  # -- Work Stream Management --

  work:list:
    desc: List all active work items in work stream
    cmds:
      - |
        echo "Active work stream items:"
        grep -E "^\\| P0|^\\| P1|^\\| P2" docs/reference/WORK_STREAM.md || echo "No items found"
    silent: true

  work:claim:
    desc: Claim a work item (usage: task work:claim -- TASK_ID)
    cmds:
      - |
        if [ -z "{{.CLI_ARGS}}" ]; then
          echo "Usage: task work:claim -- TASK_ID"
          echo "Example: task work:claim -- venture-p0-task-1"
          exit 1
        fi
        echo "Claiming {{.CLI_ARGS}} — update docs/reference/WORK_STREAM.md"

  # -- Cleanup --

  clean:
    desc: Remove generated and cache files
    cmds:
      - rm -rf .spec-index 2>/dev/null || true
      - rm -rf .linkcheck-cache 2>/dev/null || true
      - find . -name "*.bak" -delete 2>/dev/null || true
      - echo "Clean complete"

  help:
    desc: Show available tasks with descriptions
    cmds:
      - task --list
    silent: true
