📝 Documentation drift detected — `upload-build-artifact` and `hash.rs` missing from docs

[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 exists in codebase but is absent from the architecture listing	AGENTS.md
Architecture tree	src/safeoutputs/upload_build_artifact.rs exists in codebase but is not listed (only upload_workitem_attachment.rs appears)	AGENTS.md
Safe outputs table	upload-build-artifact tool is documented in docs/safe-outputs.md (§ "upload-build-artifact") but is absent from the safe outputs tool table	README.md
Safe outputs table	upload-build-artifact tool is missing from the "All configurable safe output tools" table that agents use when authoring workflows	prompts/create-ado-agentic-workflow.md

Details

1. src/hash.rs missing from AGENTS.md

src/hash.rs was added to provide SHA-256 integrity helpers shared by safe-output tools (staging and verifying files between Stage 1 and Stage 3). The AGENTS.md architecture tree lists every other top-level src/*.rs file but omits this one.

2. src/safeoutputs/upload_build_artifact.rs missing from AGENTS.md

The safeoutputs/ listing in AGENTS.md ends with upload_workitem_attachment.rs and does not include upload_build_artifact.rs. The tool is fully implemented and exported from src/safeoutputs/mod.rs.

3. upload-build-artifact missing from README.md safe outputs table

README.md's "Available Safe Output Tools" table (around line 376) lists 17 tools and includes upload-workitem-attachment but omits upload-build-artifact. The tool is fully documented in docs/safe-outputs.md § "upload-build-artifact".

4. upload-build-artifact missing from prompts/create-ado-agentic-workflow.md (high priority)

The "All configurable safe output tools" table in the prompts file (around line 271) is the primary reference AI agents use when authoring new workflow files. It currently lists upload-workitem-attachment but not upload-build-artifact. This means agents creating workflows that need to attach build artifacts will not discover the correct tool.

Suggested Fixes

• Add src/hash.rs to the architecture tree in AGENTS.md (under src/, alongside the other top-level .rs files), with a short description such as: src/hash.rs # SHA-256 integrity helpers (file staging between Stage 1 and Stage 3)
• Add src/safeoutputs/upload_build_artifact.rs to the safeoutputs/ listing in AGENTS.md
• Add upload-build-artifact row to the safe outputs table in README.md (e.g. after upload-workitem-attachment): | `upload-build-artifact` | Uploads a workspace file as an attachment to an ADO build |
• Add upload-build-artifact row to the "All configurable safe output tools" table in prompts/create-ado-agentic-workflow.md with permissions.write = ✅, under a "Builds & Branches" or similar category

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ● 779.9K · ◷