📝 Documentation drift detected — duplicate `data/` in architecture tree and incomplete write-requiring tools list

[github-actions]

Documentation Freshness Audit

The automated documentation audit found the following inconsistencies between code and documentation.

---

Findings

Area	Issue	File(s)
Architecture tree	src/data/ directory listed twice in the tree	AGENTS.md
Compile-time validation docs	Only 2 of 17 write-requiring safe-output tools named in permissions.write guidance	AGENTS.md, prompts/create-ado-agentic-workflow.md

---

Details

1. src/data/ listed twice in the architecture tree

The architecture tree in AGENTS.md (lines 25–76) shows data/ as a sub-directory of src/ twice:

• First occurrence (lines 25–26): shows only ecosystem_domains.json
• Second occurrence (lines 71–76): shows base.yml, 1es-base.yml, ecosystem_domains.json (duplicate!), init-agent.md, threat-analysis.md

In reality there is exactly one src/data/ directory in the codebase containing all five files. The first occurrence is a stale duplicate that should be removed. The correct single entry should read:

├── data/
│   ├── base.yml          # Base pipeline template for standalone
│   ├── 1es-base.yml      # Base pipeline template for 1ES target
│   ├── ecosystem_domains.json # Network allowlists per ecosystem
│   ├── init-agent.md     # Dispatcher agent template for `init` command
│   └── threat-analysis.md # Threat detection analysis prompt template
```

#### 2. Write-requiring safe-output tools list is incomplete in permissions validation guidance

Both `AGENTS.md` (line 1786) and `prompts/create-ado-agentic-workflow.md` (line 593, Key Rules section) name only `create-pull-request` and `create-work-item` when describing the `permissions.write` validation rule.

**`AGENTS.md` (line 1786):**
> "If write-requiring safe-outputs (`create-pull-request`, `create-work-item`) are configured but `permissions.write` is missing, compilation fails with a clear error message."

**`prompts/create-ado-agentic-workflow.md` (line 593):**
> "**Always validate** that write-requiring safe-outputs (`create-pull-request`, `create-work-item`) have `permissions.write` set."

However, `WRITE_REQUIRING_SAFE_OUTPUTS` in `src/safeoutputs/mod.rs` contains **17 tools**:

```
create-work-item, comment-on-work-item, update-work-item, create-pull-request,
create-wiki-page, update-wiki-page, add-pr-comment, link-work-items, queue-build,
create-git-tag, add-build-tag, create-branch, update-pr, upload-attachment,
submit-pr-review, reply-to-pr-comment, resolve-pr-thread

The incomplete list is particularly high-priority in prompts/create-ado-agentic-workflow.md because AI agents use this file directly when authoring workflows. An agent following the Key Rules section could configure (e.g.) add-pr-comment, queue-build, or create-wiki-page without setting permissions.write, and only learn of the error at compile time.

The comprehensive tool table in Step 9 of that same prompt file correctly marks all 17 tools with ✅, but the Key Rules section contradicts it by naming only 2.

---

Suggested Fixes

• Remove the duplicate data/ entry from the architecture tree in AGENTS.md (remove lines 25–26, keeping only the correct occurrence at lines 71–76, repositioned to be the single entry under src/)
• Update the permissions.write validation description in AGENTS.md to reference all write-requiring tools (or use "etc." / a link to the full list) rather than implying only create-pull-request and create-work-item trigger the validation
• Update the Key Rules section in prompts/create-ado-agentic-workflow.md to state that all write-requiring tools (not just 2) need permissions.write, e.g.: "Always validate that any write-requiring safe-output (all tools marked ✅ in the table above) is paired with permissions.write."

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ● 1.6M · ◷