📝 Documentation drift detected — missing template marker, wrong engine defaults, incomplete architecture tree

[github-actions]

Documentation Freshness Audit

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

Findings

Area	Issue	File(s)
README.md front matter table	engine field description says "AI model to use" with default claude-opus-4.5 — both are wrong	README.md
README.md Quick Start example	engine: claude-sonnet-4.5 uses a model name as the engine value — this is invalid YAML	README.md
AGENTS.md template markers	\{\{ mcpg_step_env }} exists in both pipeline templates but has no documentation section	AGENTS.md, src/data/base.yml, src/data/1es-base.yml
AGENTS.md architecture tree	src/validate.rs is not listed in the architecture directory tree	AGENTS.md
AGENTS.md architecture tree	src/compile/extensions/tests.rs is not listed in the architecture directory tree	AGENTS.md

---

Details

1. README.md — Incorrect engine field documentation (Critical)

In the Front Matter Fields table (README.md, Agent File Reference section):

| `engine` | string or object | `claude-opus-4.5` | AI model to use |
```

This is wrong on two counts:
- **Default value**: The `engine` field is an engine *identifier*, not a model name. Its default is `copilot` (see `EngineConfig::default()` in `src/compile/types.rs`). The model is a sub-field of the engine object.
- **Description**: "AI model to use" is misleading. The field selects the engine (currently only `copilot`). The model is set via `engine.model` in the object form.

The correct row should read something like:
```
| `engine` | string or object | `copilot` | Engine identifier or object with `id`, `model`, `timeout-minutes`, etc. |

---

2. README.md — Broken Quick Start example (Critical)

In the Quick Start section, the generated agent file example includes:

engine: claude-sonnet-4.5

This is invalid front matter. When the engine field is a plain string, it is parsed as the engine identifier — not a model name. Setting engine: claude-sonnet-4.5 would attempt to use an engine named claude-sonnet-4.5, which doesn't exist.

The correct way to select a non-default model is:

engine:
  id: copilot
  model: claude-sonnet-4.5
```

Or simply omit the `engine:` field entirely if using the default (`copilot` engine + `claude-opus-4.5` model).

The `prompts/create-ado-agentic-workflow.md` file correctly explains this distinction (Step 2), but `README.md` contradicts it with this bad example.

---

#### 3. `AGENTS.md` — Undocumented `\{\{ mcpg_step_env }}` template marker

The marker `\{\{ mcpg_step_env }}` appears in both:
- `src/data/base.yml` (line 285)
- `src/data/1es-base.yml` (same location)

But it has **no documentation section** in `AGENTS.md`. The compiler generates this via `generate_mcpg_step_env()` in `src/compile/common.rs` (line 1390). It produces an `env:` block for the MCPG step, forwarding pipeline variables required by extensions (e.g., `AZURE_DEVOPS_EXT_PAT`). All other markers have dedicated `## \{\{ marker_name }}` sections — this one is missing.

---

#### 4. `AGENTS.md` — Architecture tree missing `src/validate.rs`

The file `src/validate.rs` exists in the codebase (declared as `pub mod validate` in `src/main.rs`) and contains structural input validators (char allowlists, format checks, injection detectors, container/DNS validators). However it is not listed in the architecture directory tree in `AGENTS.md`. The adjacent `src/sanitize.rs` is listed.

---

#### 5. `AGENTS.md` — Architecture tree missing `src/compile/extensions/tests.rs`

The file `src/compile/extensions/tests.rs` exists but is not shown in the architecture tree under `src/compile/extensions/`. The tree currently shows only:
```
│   │   ├── mod.rs
│   │   ├── github.rs
│   │   └── safe_outputs.rs

---

Suggested Fixes

• README.md — Fix the Front Matter Fields table: change engine default from claude-opus-4.5 to copilot, update description to explain it's an engine identifier (not a model selector directly)
• README.md — Fix the Quick Start example: replace engine: claude-sonnet-4.5 with the correct object form (engine: {id: copilot, model: claude-sonnet-4.5}) or remove the engine: line if the default model is acceptable
• AGENTS.md — Add a ## \{\{ mcpg_step_env }} documentation section describing the marker's purpose: generating the env: block that forwards pipeline variables (e.g., ADO tokens) required by enabled extensions into the MCPG step
• AGENTS.md — Add validate.rs to the architecture tree with a description: "Structural input validators (char allowlists, format checks, injection detectors)"
• AGENTS.md — Add tests.rs to the compile/extensions/ section of the architecture tree

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ● 1.2M · ◷