librenotes/.wave/pipelines/doc-sync.yaml

kind: WavePipeline
metadata:
  name: doc-sync
  description: "Scan documentation for inconsistencies, fix them, and commit to a feature branch"
  release: true

input:
  source: cli
  example: "sync docs with current implementation"

steps:
  - id: scan-changes
    persona: navigator
    workspace:
      mount:
        - source: ./
          target: /project
          mode: readonly
    exec:
      type: prompt
      source: |
        Scan the repository for documentation inconsistencies: {{ input }}

        ## Process

        1. **Identify documentation files**: Find all markdown files, README,
           CONTRIBUTING, docs/ directory, inline code comments with doc references.

        2. **Identify code surface area**: Scan for exported functions, CLI commands,
           config options, environment variables, API endpoints.

        3. **Cross-reference**: For each documented feature, verify it exists in code.
           For each code feature, verify it's documented.

        4. **Check accuracy**: Compare documented behavior, flags, options, and
           examples against actual implementation.

        5. **Categorize findings**:
           - MISSING_DOCS: Feature in code, not in docs
           - STALE_DOCS: Docs reference removed/changed feature
           - INACCURATE: Docs describe wrong behavior
           - INCOMPLETE: Docs exist but missing details

        Write your findings as structured JSON.
        Include: scan_scope, findings (id, type, severity, title, doc_location, code_location,
        description, suggested_fix), summary (total_findings, by_type, by_severity, fixable_count),
        and timestamp.
    output_artifacts:
      - name: scan_results
        path: .wave/output/doc-scan.json
        type: json
    handover:
      contract:
        type: json_schema
        source: .wave/output/doc-scan.json
        schema_path: .wave/contracts/doc-sync-scan.schema.json
        on_failure: retry
        max_retries: 2

  - id: analyze
    persona: reviewer
    dependencies: [scan-changes]
    memory:
      inject_artifacts:
        - step: scan-changes
          artifact: scan_results
          as: scan
    workspace:
      mount:
        - source: ./
          target: /project
          mode: readonly
    exec:
      type: prompt
      source: |
        Review the doc scan findings and prioritize fixes.

        For each finding:
        1. Verify it's a real inconsistency (not a false positive)
        2. Assess if it can be fixed by editing docs alone
        3. Prioritize: CRITICAL/HIGH first, then by effort

        Produce a fix plan as markdown:
        - Ordered list of fixes to apply
        - For each: which file to edit, what to change, why
        - Skip items that require code changes (docs-only fixes)
        - Estimated scope of changes
    output_artifacts:
      - name: fix_plan
        path: .wave/output/fix-plan.md
        type: markdown

  - id: fix-docs
    persona: craftsman
    dependencies: [analyze]
    memory:
      inject_artifacts:
        - step: scan-changes
          artifact: scan_results
          as: scan
        - step: analyze
          artifact: fix_plan
          as: plan
    workspace:
      type: worktree
      branch: "fix/{{ pipeline_id }}"
    exec:
      type: prompt
      source: |
        Fix the documentation inconsistencies on this isolated worktree branch.

        ## Process

        1. **Apply fixes** following the priority order from the plan:
           - Edit documentation files to fix each inconsistency
           - Keep changes minimal and focused
           - Preserve existing formatting and style
           - Do NOT modify source code — docs-only changes

        2. **Verify**: Ensure no broken links or formatting issues

        3. **Commit**:
           ```bash
           git add <changed-doc-files>
           git commit -m "docs: sync documentation with implementation

           Fix N documentation inconsistencies found by doc-sync pipeline:
           - DOC-001: <title>
           - DOC-002: <title>
           ..."
           ```

        Write a summary including:
        - Branch name
        - List of files modified
        - Findings fixed vs skipped
        - Commit hash
    handover:
      contract:
        type: test_suite
        command: "{{ project.test_command }}"
        must_pass: false
        on_failure: retry
        max_retries: 2
    output_artifacts:
      - name: result
        path: .wave/output/result.md
        type: markdown

  - id: create-pr
    persona: craftsman
    dependencies: [fix-docs]
    memory:
      inject_artifacts:
        - step: scan-changes
          artifact: scan_results
          as: scan
        - step: fix-docs
          artifact: result
          as: fix_result
    workspace:
      type: worktree
      branch: "fix/{{ pipeline_id }}"
    exec:
      type: prompt
      source: |
        Create a pull request for the documentation fixes.

        ## Working Directory

        You are running in an **isolated git worktree** shared with previous pipeline steps.
        Your working directory IS the project root. The branch already exists from the
        fix-docs step — just push it and create the PR.

        ## SAFETY: Do NOT Modify the Working Tree

        This step MUST NOT run `git checkout`, `git stash`, or any command that changes
        the current branch or working tree state.

        ## Instructions

        ### Step 1: Push the Branch

        ```bash
        git push -u origin HEAD
        ```

        ### Step 2: Create Pull Request

        ```bash
        gh pr create --title "docs: sync documentation with implementation" --body "$(cat <<'PREOF'
        ## Summary

        Automated documentation sync to fix inconsistencies between docs and code.

        <summarize: N findings fixed, types of issues addressed>

        ## Changes

        <list each doc file modified and what was fixed>

        ## Findings Addressed

        <list each finding ID, type, and resolution>

        ## Skipped

        <list any findings that were skipped and why>
        PREOF
        )"
        ```

        ### Step 3: Request Copilot Review (Best-Effort)

        ```bash
        gh pr edit --add-reviewer "copilot" 2>/dev/null || true
        ```

        ## CONSTRAINTS

        - Do NOT spawn Task subagents — work directly in the main context
        - Do NOT run `git checkout`, `git stash`, or any branch-switching commands
        - Do NOT include Co-Authored-By or AI attribution in commits

    output_artifacts:
      - name: pr-result
        path: .wave/output/pr-result.json
        type: json
    handover:
      contract:
        type: json_schema
        source: .wave/output/pr-result.json
        schema_path: .wave/contracts/pr-result.schema.json
        must_pass: true
        on_failure: retry
        max_retries: 2
    outcomes:
      - type: pr
        extract_from: .wave/output/pr-result.json
        json_path: .pr_url
        label: "Pull Request"