📝 Documentation drift detected — missing files in architecture tree, wrong field names, and missing safe-output tool

[github-actions]

Documentation Freshness Audit

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

Findings

Area	Issue	File(s)
Architecture tree	src/hash.rs missing from directory listing	AGENTS.md
Architecture tree	src/safeoutputs/upload_build_artifact.rs missing from directory listing	AGENTS.md
Safe output tools	upload-build-artifact tool missing from table	README.md
Safe output tools	upload-build-artifact tool missing from table	prompts/create-ado-agentic-workflow.md
Front matter fields	README lists field as triggers but actual YAML key is on:	README.md
Front matter example	Top-level example shows schedule: as a top-level field, but no such field exists — schedule is under on: schedule:	docs/front-matter.md

Details

1. AGENTS.md — missing files in architecture tree

Two source files exist in the codebase but are absent from the src/ directory tree in AGENTS.md:

• src/hash.rs — present in src/main.rs module declarations (mod hash;) but not listed in the architecture tree.
• src/safeoutputs/upload_build_artifact.rs — the tree only shows upload_workitem_attachment.rs but upload_build_artifact.rs also exists and is exported from src/safeoutputs/mod.rs.

2. README.md — upload-build-artifact missing from safe output tools table

The safe output tools table (around line 374–396) lists all other tools but omits upload-build-artifact. The tool is fully implemented in src/safeoutputs/upload_build_artifact.rs and documented in docs/safe-outputs.md (§ upload-build-artifact).

3. prompts/create-ado-agentic-workflow.md — upload-build-artifact missing

The "All configurable safe output tools" table (§ Builds & Branches group) lists queue-build, create-branch, create-git-tag, and add-build-tag, but does not include upload-build-artifact. This is the primary guide agents use when authoring workflows, so the omission will cause agents to be unaware of this capability.

4. README.md — wrong field name in Front Matter Fields table

The Front Matter Fields table (around line 247) contains:

| `triggers` | object | — | Pipeline trigger configuration |

But the actual YAML key in the front matter is on: — see src/compile/types.rs:

#[serde(default, rename = "on")]
pub on_config: Option<OnConfig>,

There is no triggers: field. Using triggers: in a pipeline definition will be silently ignored (the FrontMatter struct does not use #[serde(deny_unknown_fields)]), causing the trigger to never fire.

5. docs/front-matter.md — top-level example shows schedule: as a top-level field

The full example block near the top of docs/front-matter.md (around line 19) shows:

schedule: daily around 14:00 # Fuzzy schedule syntax - see docs/schedule-syntax.md

as a top-level front matter field, but FrontMatter has no top-level schedule field. Schedule is nested under the on: key:

on:
  schedule: daily around 14:00

The same file correctly shows the on: form later (around line 74), but the top-level example contradicts it. The standalone schedule: at the top level would be silently ignored at compile time.

Suggested Fixes

• Add src/hash.rs and src/safeoutputs/upload_build_artifact.rs to the architecture tree in AGENTS.md
• Add upload-build-artifact row to the safe output tools table in README.md
• Add upload-build-artifact row to the "All configurable safe output tools" table in prompts/create-ado-agentic-workflow.md
• Fix triggers → on in the Front Matter Fields table in README.md
• Fix the top-level example in docs/front-matter.md to move schedule: under on: (or remove it from the top-level block and rely on the on: section below)

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ● 1.8M · ◷