📝 Documentation drift detected — missing `configure` command, undocumented source files, incorrect `compile` synopsis

[github-actions]

Documentation Freshness Audit

The weekly documentation audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
Architecture	src/configure.rs exists but is not listed in the architecture tree	src/configure.rs, .github/copilot-instructions.md
Architecture	src/detect.rs exists but is not listed in the architecture tree	src/detect.rs, .github/copilot-instructions.md
CLI Commands	configure subcommand is fully implemented but completely undocumented	src/main.rs, .github/copilot-instructions.md
CLI Commands	compile (path) documents (path) as required, but it is optional (auto-discovery mode when omitted)	src/main.rs, .github/copilot-instructions.md

Details

1. Undocumented source files

The architecture tree in .github/copilot-instructions.md lists files under src/ but is missing two modules:

• src/configure.rs — Implements the configure CLI command. Scans for compiled agentic pipelines and updates the GITHUB_TOKEN pipeline variable on their ADO build definitions.
• src/detect.rs — Supports configure.rs. Scans a directory for *.yml/*.yaml files with the # @ado-aw`` header marker and extracts pipeline metadata (yaml path, source markdown path, compiler version).

2. Missing configure subcommand documentation

src/main.rs defines a Configure variant in the Commands enum that is not mentioned anywhere in .github/copilot-instructions.md. The command has the following interface:

configure  Detect agentic pipelines and update GITHUB_TOKEN on their ADO definitions

Options:
  --token (TOKEN)             New GITHUB_TOKEN value [env: GITHUB_TOKEN]
  --org (ORG)                 Azure DevOps organization URL (inferred from git remote)
  --project (PROJECT)         Azure DevOps project name (inferred from git remote)
  --pat (PAT)                 PAT for ADO API auth [env: AZURE_DEVOPS_EXT_PAT]
  --path (PATH)               Path to repository root (default: current directory)
  --dry-run                   Preview changes without applying them
  --definition-ids (IDS,...)  Explicit pipeline definition IDs to update (skips auto-detection)

3. Incorrect compile path synopsis

The docs describe the compile command as:

compile (path) — Compile a markdown file to Azure DevOps pipeline YAML

In src/main.rs, path is declared as Option(String), making it optional. When omitted, the compiler enters auto-discovery mode and recompiles all detected pipelines in the repository (the --output flag is also rejected in this mode). The documented synopsis should be:

compile [(path)] — Compile a markdown file to Azure DevOps pipeline YAML, or recompile all detected pipelines if no path is given

Suggested Fixes

• Add src/configure.rs and src/detect.rs to the architecture tree in .github/copilot-instructions.md
• Document the configure command in the CLI Commands section, including all flags and their defaults
• Update the compile command synopsis to show [(path)] as optional and document the auto-discovery behaviour

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ◷