feat(safeoutputs): add ado-aw-debug.create-issue for dogfood pipelines

[jamesadevine]

Summary

Adds a new top-level ado-aw-debug: front-matter section that gates two debug-only knobs intended for dogfooding ado-aw pipelines from Azure DevOps back into githubnext/ado-aw:

• skip-integrity: bool — OR-ed with the existing --skip-integrity CLI flag.
• create-issue: — files a GitHub issue against an operator-configured target repo when the agent calls the new create-issue MCP tool.

The create-issue tool is not a regular safe output. It is default-deny at three independent layers — the MCP filter, the compiler, and Stage 3 — so it can't be reached unless the operator explicitly opts in via ado-aw-debug.create-issue:.

Front-matter shape

ado-aw-debug:
  skip-integrity: true                    # optional; OR-ed with --skip-integrity
  create-issue:
    target-repo: githubnext/ado-aw        # required; operator-only (agent can't override)
    title-prefix: "[pipeline-failure] "
    labels: [pipeline-failure]
    allowed-labels: ["agent-*"]           # default-DENY (empty = no agent labels)
    assignees: [jamesdevine]
    max: 3

Three-layer default-deny gate

1. MCP layer — DEBUG_ONLY_TOOLS strips create-issue from the SafeOutputs router unless explicitly enabled. Holds even when --enabled-tools is empty (the regular permissive default).
2. Compiler layer — --enabled-tools create-issue is emitted only when ado-aw-debug.create-issue: is set; safe-outputs.create-issue: is rejected outright at compile time so the tool can't be smuggled in via the regular safe-outputs surface.
3. Executor layer — new ExecutionContext.debug_enabled_tools set is populated only from ado-aw-debug:. Stage 3 refuses any create-issue NDJSON entry whose tool name is absent from that set, closing the gap where a forged entry could otherwise bypass the MCP-layer gate.

The third layer was added in response to a rubber-duck review that surfaced the MCP-only gate as insufficient for a write-capable GitHub PAT.

Stage 3 PAT plumbing

• New dedicated ADO_AW_DEBUG_GITHUB_TOKEN ADO pipeline variable, separate from the read-only GITHUB_TOKEN the agent sees in Stage 1.
• New ExecutionContext.github_token: Option<String> field, sourced from that env var.
• Executor uses GitHub REST API: POST /repos/{owner}/{repo}/issues with bearer token, User-Agent: ado-aw/{version}, and X-GitHub-Api-Version: 2022-11-28.
• Auto-footer with stable <!-- ado-aw --> marker, build ID, run URL, pipeline name, and trigger reason.

Other rubber-duck-driven hardenings

• allowed-labels: [] is now default-deny — operators must opt in to unrestricted with ["*"].
• Tightened target-repo regex to match GitHub's login spec (no underscores or dots in owner segments).
• Final issue title length validated after title-prefix application.
• Stage 3 error messages neutralise ##vso[…] sequences in agent-supplied labels so a forged NDJSON entry can't echo a live pipeline command into stdout.

Files

• New: src/safeoutputs/create_issue.rs, docs/ado-aw-debug.md, examples/dogfood-failure-reporter.md, tests/fixtures/ado-aw-debug-agent.md.
• Modified: 14 files across compiler, MCP server, executor, types, docs, and integration tests.
• Diff: 18 files, +1,888/-46.

Out of scope (per planning Q&A)

• Pipeline-failure detection workflow that uses create-issue (separate decision).
• gh-aw parity beyond the minimal field set (sub-issues, group-by-day, close-older, etc.).
• Automated provisioning of the ADO_AW_DEBUG_GITHUB_TOKEN variable via ado-aw configure.

Test plan

• Unit tests in src/safeoutputs/create_issue.rs — 23 tests covering deserialisation, validation, sanitisation, the three-layer gate (including a forged-NDJSON scenario), default-deny allowed-labels, post-prefix title-length validation, neutralisation of pipeline-command sequences in error strings, and target-repo regex edge cases.
• MCP filter tests in src/mcp.rs — 3 new tests asserting create-issue is stripped when enabled_tools is None, present when explicitly enabled, and stripped when other tools are enabled but create-issue isn't. Coverage test (test_all_known_safe_outputs_covers_router) updated to exempt DEBUG_ONLY_TOOLS.
• Compiler tests in src/compile/common.rs — coverage for generate_executor_ado_env (both tokens, each in isolation, neither), generate_enabled_tools_args (debug alone, debug + safe-outputs, no debug), validate_ado_aw_debug_config (missing target-repo, malformed target-repo, pipeline-injection in labels and title-prefix, redirection from safe-outputs.create-issue), and integrity OR-ing.
• Front-matter tests in src/compile/types.rs — round-trip of ado-aw-debug:, deny_unknown_fields enforcement.
• Integration test in tests/compiler_tests.rs — test_compile_ado_aw_debug_fixture compiles tests/fixtures/ado-aw-debug-agent.md and asserts (a) integrity step omitted, (b) executor env: block exposes ADO_AW_DEBUG_GITHUB_TOKEN, (c) --enabled-tools create-issue is wired in, (d) output is valid YAML. Plus a structural smoke test for the new example file.

cargo test          → 1,356 passed, 0 failed (added ~30 targeted tests)
cargo build         → clean
cargo clippy --all-targets -- -D warnings   → 106 errors (baseline; 0 net-new)

Release-mode test failures (11) are pre-existing: --skip-integrity and --debug-pipeline are debug-only CLI flags by design.

[github-actions]

🔍 Rust PR Review

Summary: Looks good overall — the three-layer default-deny design is sound and the security thinking is thorough. One logic bug worth fixing before merge.

Findings

🐛 Bugs / Logic Issues

• src/main.rs:316 — ctx.debug_enabled_tools.insert("create-issue") runs unconditionally after the match serde_json::to_value(ci) block, meaning it fires even when the Err arm is taken. If serialization ever fails, Stage 3 would see create-issue in debug_enabled_tools but find no matching entry in tool_configs, causing get_tool_config to return Default::default() → validate_target_repo("") → a confusing "target-repo is required" error instead of a serialization failure. serde_json::to_value on a String/Vec<String> struct will never fail in practice, but the placement is wrong structurally. The insert belongs inside the Ok(v) arm:

  match serde_json::to_value(ci) {
      Ok(v) => {
          ctx.tool_configs.insert("create-issue".to_string(), v);
          ctx.debug_enabled_tools.insert("create-issue".to_string()); // ← move here
      }
      Err(e) => log::warn!("Failed to serialize ado-aw-debug.create-issue config: {e}"),
  }
  // remove the dangling insert

⚠️ Suggestions

• src/safeoutputs/create_issue.rs:~200 — merge_labels is called for both labels and assignees (merge_labels(&config.assignees, &self.assignees)). The logic is identical so it works, but the name is misleading for a future reader. A rename to merge_dedup_strings (or a private merge_string_lists) would make the intent clearer.

• src/safeoutputs/create_issue.rs:~50 — title.len() and body.len() are byte-lengths, not Unicode scalar counts. Unlikely to matter for ADO pipeline titles (almost always ASCII), and GitHub's own character counting is char-based, not byte-based. Not a blocker, but worth a comment that the limit is in bytes, not chars.

✅ What Looks Good

• Three-layer gate is architecturally correct: MCP filter (DEBUG_ONLY_TOOLS), compiler (--enabled-tools injection gated on front-matter), and executor (debug_enabled_tools check before any network call). The forged-NDJSON scenario is explicitly covered.
• PAT separation: ADO_AW_DEBUG_GITHUB_TOKEN deliberately kept separate from SYSTEM_ACCESSTOKEN and the read-only GITHUB_TOKEN the agent sees. The comment in result.rs makes this invariant clear.
• reject_pipeline_injection applied exhaustively across all operator-supplied config fields (target-repo, title-prefix, labels, allowed-labels, assignees) at compile time.
• ##vso[...] neutralized in error paths: agent-supplied labels are passed through neutralize_pipeline_commands before being echoed into the failure message, preventing ADO command injection even through the error surface.
• target-repo regex correctly rejects underscores and dots in the owner segment (matching GitHub's actual login rules), and the extra . / .. guard after the regex is correctly belt-and-suspenders.
• deny_unknown_fields on AdoAwDebugConfig prevents typos from silently passing as no-ops.
• Test coverage is comprehensive — the forged-NDJSON scenario, default-deny allowed-labels, post-prefix title-length, and all three MCP filter scenarios are all exercised.

Generated by Rust PR Reviewer for issue #492 · ● 504.3K · ◷