📝 Documentation drift detected — `tools:` field, 1ES `\{\{ workspace }}` marker, engine options

[github-actions]

Documentation Freshness Audit

The weekly documentation audit found the following inconsistencies between code and documentation (AGENTS.md):

Findings

Area	Issue	File(s)
Front Matter Fields	tools: is documented as RESERVED / not yet implemented but is fully implemented	AGENTS.md line 123 vs src/compile/common.rs
Template Markers	\{\{ workspace }} is not replaced in the 1ES compiler, leaving literal placeholder in output	AGENTS.md \{\{ workspace }} section vs src/compile/onees.rs
Front Matter Fields	engine.max-turns and engine.timeout-minutes are documented and parsed but silently ignored by both compilers	AGENTS.md lines 101–102 vs src/compile/common.rs

Details

1. tools: field documented as RESERVED but fully implemented

AGENTS.md line 123 comments out the tools: field with:

# tools:                       # RESERVED: tool configuration (not yet implemented)
#   bash: ["cat", "ls", "grep"]  # bash command allow-list
#   edit: true                   # enable file editing tool

However, src/compile/common.rs generate_copilot_params() actively consumes both tools.bash and tools.edit:

• tools.edit controls whether --allow-tool write is added (defaults to true)
• tools.bash overrides the default bash command allow-list (supports [":*"] for unrestricted access, empty list to disable, or an explicit list)

The field is fully functional — users who follow the docs will miss this capability entirely.

2. \{\{ workspace }} not replaced in 1ES compiler

AGENTS.md documents \{\{ workspace }} as:

An alias for \{\{ working_directory }}. Both markers are replaced with the same value based on the effective workspace setting.

src/compile/common.rs generate_source_path() and generate_pipeline_path() return strings like \{\{ workspace }}/agents/(file).md and \{\{ workspace }}/(file).yml respectively. These functions are called by both compilers.

• Standalone (src/compile/standalone.rs line 164): ✅ replaces \{\{ workspace }} → resolves correctly
• 1ES (src/compile/onees.rs): ❌ no \{\{ workspace }} replacement — \{\{ source_path }} and \{\{ pipeline_path }} in 1ES-generated pipelines end up containing the literal string \{\{ workspace }}/agents/(file).md

This affects the integrity check step (ado-aw check) and the execute step in all 1ES pipelines.

3. engine.max-turns and engine.timeout-minutes silently ignored

The documented example YAML shows:

# engine:
#   model: claude-opus-4.5
#   max-turns: 50           # line 101
#   timeout-minutes: 30     # line 102

src/compile/types.rs correctly parses these into EngineOptions.max_turns and EngineOptions.timeout_minutes, and EngineConfig exposes max_turns() and timeout_minutes() accessors. However, neither src/compile/standalone.rs nor src/compile/onees.rs calls these accessors — generate_copilot_params() only uses engine.model(). The options are silently discarded.

Suggested Fixes

• tools: field — Remove the RESERVED comment and uncomment the example in AGENTS.md. Document tools.bash (default command list, [":*"] for unrestricted) and tools.edit (default true) with their actual behavior.
• \{\{ workspace }} in 1ES — Add ("\{\{ workspace }}", &working_directory) to the replacements list in src/compile/onees.rs (matching standalone line 164), and clarify in AGENTS.md that the marker applies to both targets.
• engine.max-turns / engine.timeout-minutes — Either pass these as --max-turns / --timeout-minutes flags to agency in generate_copilot_params(), or mark them as reserved/future in AGENTS.md to set correct expectations.

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ◷