📝 Documentation drift detected — missing safe output tools in prompts + missing hash.rs in AGENTS.md

[github-actions]

Documentation Freshness Audit

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

Findings

Area	Issue	File(s)
Workflow authoring prompt	upload-pipeline-artifact and upload-build-attachment are missing from the "All configurable safe output tools" table	prompts/create-ado-agentic-workflow.md
Architecture tree	src/hash.rs is not listed in the architecture tree	AGENTS.md

Details

1. prompts/create-ado-agentic-workflow.md — Two safe output tools missing from the table (HIGH PRIORITY)

The file's "All configurable safe output tools" table (Step 9, around line 272) lists 22 tools across Work Items, Pull Requests, Builds & Branches, Wiki, and Diagnostics categories. However, two tools that exist in src/safeoutputs/ and are fully documented in docs/safe-outputs.md and README.md are absent:

Missing tool	Source file	write = true
upload-pipeline-artifact	src/safeoutputs/upload_pipeline_artifact.rs:117	✅
upload-build-attachment	src/safeoutputs/upload_build_attachment.rs:122	✅

Both tools are documented correctly in docs/safe-outputs.md (lines ~421–498) and in the README.md safe-outputs table (lines ~393–394). Because prompts/create-ado-agentic-workflow.md is the primary guide AI agents use when creating new workflows, omitting these tools means agents will not know they can propose build artifact uploads, leading to missed capabilities or hand-coded workarounds.

Both tools should be added to the Builds & Branches group of the table (after add-build-tag):

| `upload-build-attachment` | Attach a workspace file to a build (visible via REST/custom extension) | ✅ |
| `upload-pipeline-artifact` | Publish a workspace file as a pipeline artifact (visible in Artifacts tab) | ✅ |

2. AGENTS.md — src/hash.rs missing from architecture tree

src/hash.rs exists in the repository:

// src/hash.rs — Cryptographic hash utilities shared across the crate.
// Used by safe-output tools to record and verify file integrity between
// Stage 1 (MCP, in-sandbox) and Stage 3 (executor, outside sandbox).
pub(crate) fn sha256_hex(data: &[u8]) -> String { ... }

It is not listed anywhere in the architecture tree under src/ in AGENTS.md. The tree currently jumps from agent_stats.rs directly to safeoutputs/, skipping hash.rs.

Suggested Fixes

• Add upload-build-attachment and upload-pipeline-artifact to the safe outputs table in prompts/create-ado-agentic-workflow.md (Step 9), in the Builds & Branches group, after add-build-tag, noting permissions.write: ✅ for both
• Add ├── hash.rs # SHA-256 utilities for safe-output file integrity to the src/ architecture tree in AGENTS.md (between fuzzy_schedule.rs and init.rs, or between agent_stats.rs and safeoutputs/)

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ● 2.1M · ◷