📝 Documentation drift detected — architecture tree duplication, missing template marker, incorrect engine field description

[github-actions]

Documentation Freshness Audit

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

Findings

Area	Issue	File(s)
Architecture tree	src/data/ directory listed twice — first with only ecosystem_domains.json, then correctly with all files	AGENTS.md
Architecture tree	src/run.rs (debug-only local dev command) is absent from the architecture tree	AGENTS.md
Template markers	\{\{ mcpg_step_env }} is used in both base.yml and 1es-base.yml but has no documentation entry	AGENTS.md
Front Matter Fields table	engine row shows default claude-opus-4.5 and description "AI model to use" — both wrong; engine is the engine identifier (defaults to copilot); the model is a sub-field	README.md

Details

1. Duplicate src/data/ in architecture tree (AGENTS.md lines 25 and 76)

The architecture tree contains two separate data/ entries nested under src/:

│   ├── data/
│   │   └── ecosystem_domains.json   ← line 25 (incomplete, only one file listed)
...
│   ├── data/
│   │   ├── base.yml                 ← line 76 (correct, lists all files)
│   │   ├── 1es-base.yml
│   │   ├── ecosystem_domains.json
│   │   ├── init-agent.md
│   │   └── threat-analysis.md

Only one src/data/ directory exists on disk. The first entry (line 25) is a stale remnant and should be removed.

2. Missing src/run.rs (AGENTS.md)

src/run.rs exists in the codebase (debug-only, gated with #[cfg(debug_assertions)]). It implements the run subcommand for local development. The architecture tree doesn't list it. Since it was already referenced in the CLI commands section of AGENTS.md as a debug-only run command, it should also appear in the architecture tree.

3. Undocumented \{\{ mcpg_step_env }} template marker (AGENTS.md)

Both src/data/base.yml and src/data/1es-base.yml include the \{\{ mcpg_step_env }} marker (at line 285 of base.yml). The corresponding function generate_mcpg_step_env() in src/compile/common.rs (line 1677) generates ADO env: block entries for secret pipeline variable passthrough to MCPG steps (used when extensions like Azure DevOps MCP require token variables). This marker is not documented in the template markers section of AGENTS.md.

Every other template marker in both .yml files has a corresponding ## \{\{ marker_name }} section in AGENTS.md. \{\{ mcpg_step_env }} is the only one missing.

4. Incorrect engine field in README.md Front Matter table (README.md line 228)

The table currently reads:

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

This is wrong in two ways:

• Default value should be copilot, not claude-opus-4.5. The engine identifier string defaults to copilot; claude-opus-4.5 is the default for the model sub-field within the engine object.
• Description should be "Engine identifier (e.g., copilot); use object form to set model" — the field selects which AI runtime to use, not which model.

This is confirmed by src/compile/types.rs where EngineConfig defaults to Simple("copilot") and by src/engine.rs where DEFAULT_COPILOT_MODEL = "claude-opus-4.5" is the model default.

Suggested Fixes

• Remove the duplicate data/ entry at line 25 of the AGENTS.md architecture tree (keep only the complete entry at line 76)
• Add src/run.rs to the AGENTS.md architecture tree with annotation # Local agent runner (debug builds only)
• Add a ## \{\{ mcpg_step_env }} section to AGENTS.md documenting that this marker generates the ADO env: block for secret pipeline variable passthrough (e.g., SC_READ_TOKEN: $(SC_READ_TOKEN)) when extensions require token forwarding to MCPG steps
• Fix the engine row in README.md's Front Matter Fields table: change default from claude-opus-4.5 to copilot and update description to reflect that engine is an engine identifier, not a model name

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ● 982.7K · ◷