### reproduction command
$ zig build test

### documentation-link check output
    FAIL docs/authoring-spine.md:5: link 'contracts/README.md#rules-of-use' -> heading '#rules-of-use' not found in docs/contracts/README.md
    FAIL docs/changelog.d/953-editor-reading-hierarchy-and-host-contract.md:12: link '/editor/README.md#reading-hierarchy-and-pane-headers' -> heading '#reading-hierarchy-and-pane-headers' not found in <repo>/editor/README.md
    FAIL docs/contracts/cli.md:97: link '#machine-readable-reports' -> heading '#machine-readable-reports' not found in <repo>/docs/contracts/cli.md
    FAIL docs/contracts/diagnostics.md:331: link 'cli.md#stdout-machine-surface' -> heading '#stdout-machine-surface' not found in docs/contracts/cli.md
    FAIL docs/contracts/html-output.md:209: link '#status-gating-on-the-default-html-target-738' -> heading '#status-gating-on-the-default-html-target-738' not found in <repo>/docs/contracts/html-output.md
    FAIL docs/contracts/validation.md:46: link 'diagnostics.md#html-path-machine-readable-report' -> heading '#html-path-machine-readable-report' not found in docs/contracts/diagnostics.md
==> 1073 links checked
doc-links: 31 broken link(s)
test
+- run bash failure
error: process exited with error code 1
failed command: cd <repo> && bash scripts/test-doc-links.sh

Build Summary: 202/204 steps succeeded (1 failed); 15469/15484 tests passed (15 skipped)
test transitive failure
+- run bash failure

error: the following build command failed with exit code 1:
zig build test (transitive build command exited with code 1)

## Code Analysis

### Aggregate test includes the documentation-link gate
`build.zig:1933-1938`
```zig
test_step.dependOn(&run_invariants_tests.step);
test_step.dependOn(&run_emitter_discipline_tests.step);
test_step.dependOn(&run_emitter_hostile_tests.step);
test_step.dependOn(&emitter_registry.step);
test_step.dependOn(&doc_links_run.step);
test_step.dependOn(&github_pages_audit_test.step);
```
The aggregate `test` step directly depends on `doc_links_run`, so the documentation-link result contributes to `zig build test`.

### The link guard fails when broken links remain
`scripts/test-doc-links.sh:162-186`
```bash
note "walking internal links in README.md and the whole docs/ tree"
check_file README.md
while IFS= read -r file; do
  [ -n "$file" ] || continue
  is_skipped_tree "$file" && continue
  check_file "$file"
done < <(find docs -name '*.md' | sort)

if [ "$failures" -ne 0 ]; then
  printf 'doc-links: %d broken link(s)\n' "$failures" >&2
  exit 1
fi
echo "doc-links: all assertions passed"
```
The source makes the observed behavior an intentional hard-failing gate: each broken link increments `failures`, and any nonzero count exits with status 1.

### Result
The captured aggregate run found 31 broken documentation anchors and exited with code 1 after 202 of 204 build steps succeeded. This supports the reported failure of the aggregate documentation-link verification gate.