docs: fix documentation drift — env field status and export-gate-schema command

[github-actions]

Documentation Freshness Audit

This audit compared project documentation against the actual codebase to identify drift between docs and implementation. The audit checked:

1. CLI commands (src/main.rs vs docs/cli.md)
2. Front matter fields (src/compile/types.rs vs docs/front-matter.md)
3. Template markers (src/data/*.yml vs docs/template-markers.md)
4. Safe output tools (src/safeoutputs/ vs docs/safe-outputs.md)
5. Architecture tree (AGENTS.md vs actual directory structure)

Findings

Area	Issue	File(s)
Front matter field	env: marked as "RESERVED: not yet implemented" but is actually implemented	docs/front-matter.md:60-61
CLI command	export-gate-schema hidden build-time tool was undocumented	docs/cli.md

Details

1. env: Field Status (CRITICAL)

docs/front-matter.md:60-61 incorrectly marked the env: field as "RESERVED" with a comment stating it was "not yet implemented":

# env:                          # RESERVED: workflow-level environment variables (not yet implemented)
#   CUSTOM_VAR: "value"

However, src/compile/types.rs:125-127 shows the field is fully implemented:

/// Workflow-level environment variables
#[serde(default)]
pub env: HashMap<String, String>,

Impact: Users were told a working feature was unavailable, preventing them from using workflow-level environment variables.

Fix: Removed the "RESERVED" comment and uncommented the example, showing the field as available.

2. export-gate-schema Command (DOCUMENTATION GAP)

The export-gate-schema command exists in src/main.rs:424-431:

#[command(hide = true)]
ExportGateSchema {
    /// Output path; if omitted, prints to stdout.
    #[arg(short, long)]
    output: Option<std::path::PathBuf>,
},

It was referenced in docs/cli.md:120-122 but never introduced or explained in the main command list.

Impact: Contributors working on the scripts/ado-script TypeScript workspace had no documentation for this build-time tool.

Fix: Added a new "Hidden Build-Time Tools" section in docs/cli.md documenting export-gate-schema with usage and context.

Applied Fixes

• Uncommented env: field in docs/front-matter.md and removed incorrect "RESERVED" status
• Documented export-gate-schema in new "Hidden Build-Time Tools" section in docs/cli.md

Verified Accurate (No Changes Needed)

• ✅ CLI commands — all commands in src/main.rs Commands enum are documented
• ✅ Template markers — all markers in base.yml, 1es-base.yml, job-base.yml, stage-base.yml are documented in docs/template-markers.md
• ✅ Safe output tools — all 24 tools in src/safeoutputs/ are documented in docs/safe-outputs.md
• ✅ FrontMatter fields — all fields in src/compile/types.rs are documented across docs/front-matter.md and linked concept docs
• ✅ Architecture tree — AGENTS.md:44-150 accurately reflects actual directory structure
• ✅ Schedule syntax — docs/schedule-syntax.md matches src/fuzzy_schedule.rs

---

This pull request was created by the automated documentation freshness check workflow.

Generated by Documentation Freshness Check · ● 1.6M · ◷