diff --git a/docs/src/content/docs/specs/safe-outputs-specification.md b/docs/src/content/docs/specs/safe-outputs-specification.md
index a21c8cb5381..31625127731 100644
--- a/docs/src/content/docs/specs/safe-outputs-specification.md
+++ b/docs/src/content/docs/specs/safe-outputs-specification.md
@@ -7,7 +7,7 @@ sidebar:
# Safe Outputs MCP Gateway Specification
-**Version**: 1.28.2
+**Version**: 1.28.3
**Status**: Working Draft
**Publication Date**: 2026-08-07
**Editor**: GitHub Agentic Workflows Team
@@ -5423,6 +5423,11 @@ This specification revision aligns with directly relevant `CHANGELOG.md` entries
- **Earlier changelog entry**: status comments were decoupled from default AI reaction behavior; explicit `on.status-comment` configuration is required when status comments are desired.
- **Earlier changelog entry**: `command` trigger was renamed to `slash_command` with deprecation compatibility.
+**Version 1.28.3** (2026-08-14):
+
+- **Editorial-only**: Added the [safe-outputs scratchpad removal checklist](https://github.com/github/gh-aw/blob/main/specs/safe-outputs-scratchpad-removal.md) to track deletion of a deprecated scratchpad document by 2026-09-21; no normative requirements changed.
+- **Updated**: Publication metadata to 1.28.3.
+
**Version 1.28.2** (2026-08-07):
- **Added**: Controlled `add_comment.comment_id` support for wildcard comment targets. Agent-supplied comment IDs MAY be accepted only when `safe-outputs.add-comment.target` is `"*"` and the exact positive integer ID appears in trusted `safe-outputs.add-comment.allows-comment-ids` workflow state.
diff --git a/scratchpad/guard-policies-specification.md b/scratchpad/guard-policies-specification.md
index 0e7be8098dc..dcfbc64655f 100644
--- a/scratchpad/guard-policies-specification.md
+++ b/scratchpad/guard-policies-specification.md
@@ -33,7 +33,7 @@ The user requested support for guard policies in the MCP gateway configuration,
3. Expose these parameters through workflow frontmatter fields
-## Proposed Solution
+## Approach
### 1. Type Hierarchy
@@ -102,6 +102,8 @@ tools:
> **Note**: The field was originally named `repos` and renamed to `allowed-repos` in PR #22331. The old name is retained as a deprecated alias; run `gh aw fix` to migrate automatically.
+## Operations
+
### 4. MCP Gateway Configuration Flow
1. **Frontmatter Parsing** (`tools_parser.go`):
@@ -582,6 +584,10 @@ The deprecated `repos` field (YAML key: `repos`) is handled alongside `allowed-r
This section lists the files that **MUST** be reviewed and updated whenever a normative section of this specification changes. Reviewers **SHALL** confirm each target is consistent with the updated spec before merging.
+### After Restructuring Approach and Operations Headers
+
+The Approach and Operations headers organize the former Proposed Solution and MCP Gateway Configuration Flow content. Keep these headers in place when synchronizing this scratchpad document with downstream documentation or navigation.
+
### After Adding or Changing Normative Requirements (§Conformance)
When requirements GP-01–GP-11 (or any later additions) change, update the following:
diff --git a/scratchpad/safe-outputs-specification.md b/scratchpad/safe-outputs-specification.md
index 6bf025a4153..0bdecf5b53c 100644
--- a/scratchpad/safe-outputs-specification.md
+++ b/scratchpad/safe-outputs-specification.md
@@ -10,20 +10,20 @@ sidebar:
> This scratchpad file (v1.1.0) is significantly outdated relative to the canonical specification.
> **Do not use this document for implementation reference.**
>
-> **Canonical version**: [Safe Outputs MCP Gateway Specification v1.21.0](/gh-aw/specs/safe-outputs-specification/)
+> **Canonical version**: [Safe Outputs MCP Gateway Specification v1.28.3](/gh-aw/specs/safe-outputs-specification/)
> (`docs/src/content/docs/specs/safe-outputs-specification.md`)
>
> This file is retained for historical reference only. It documents the original v1.x architecture
> prior to the MCP Gateway refactor. For all normative requirements, conformance testing, and
-> implementation guidance, refer to the canonical v1.21.0 specification linked above.
+> implementation guidance, refer to the canonical v1.28.3 specification linked above.
>
-> **Archival Notice**: This file is scheduled for **deletion on or before 2026-09-21** (90 days from 2026-06-21 audit date). After that date, any remaining references to this scratchpad file in doc-site navigation, workflow files, or internal links **MUST** be updated to point to the canonical path `docs/src/content/docs/specs/safe-outputs-specification.md`. To request a deletion-date extension, open an issue with the `docs` label and tag `@gh-aw-team`.
+> **Archival Notice**: This file is scheduled for **deletion on or before 2026-09-21** (90 days from 2026-06-21 audit date). Complete the [tracked removal checklist](../specs/safe-outputs-scratchpad-removal.md) before that date. After that date, any remaining references to this scratchpad file in doc-site navigation, workflow files, or internal links **MUST** be updated to point to the canonical path `docs/src/content/docs/specs/safe-outputs-specification.md`. To request a deletion-date extension, open an issue with the `docs` label and tag `@gh-aw-team`.
# Safe Outputs System Specification
**Version**: 1.1.0
-**Status**: ~~Recommendation~~ **DEPRECATED** (superseded by v1.21.0)
-**Latest Version**: https://github.github.com/gh-aw/scratchpad/safe-outputs-specification/
+**Status**: ~~Recommendation~~ **DEPRECATED** (superseded by v1.28.3)
+**Latest Version**: https://github.com/github/gh-aw/blob/main/scratchpad/safe-outputs-specification.md
**Editors**: GitHub Next Team
---
diff --git a/specs/awf-config-sources-spec.md b/specs/awf-config-sources-spec.md
index 469946fc9d0..5262ad39f74 100644
--- a/specs/awf-config-sources-spec.md
+++ b/specs/awf-config-sources-spec.md
@@ -290,4 +290,4 @@ When canonical sources in `github/gh-aw-firewall` are unavailable (GitHub outage
1. The workflow **MUST** attempt to use the last-known validated local snapshot (for example cached schema/spec artifacts from the previous successful run) to keep checks deterministic. The snapshot **MUST** be stored at a stable, well-known path: `~/.cache/gh-aw/schema-consistency/last-known-snapshot/` on self-hosted runners or `/tmp/gh-aw/agent/schema-consistency/last-known-snapshot/` when the runner is ephemeral. Snapshots older than **7 days** (168 hours from the `detected_at` timestamp of the last successful refresh) **MUST** be treated as expired and **MUST NOT** be used to suppress drift warnings; when a snapshot is expired, the run **MUST** be marked degraded even if the snapshot files are physically present. Implementations **SHOULD** delete snapshots older than 14 days to prevent unbounded disk use.
2. The workflow **SHOULD** emit a warning that canonical source retrieval failed, including the failing source path(s) and timestamp.
3. The workflow **MUST** skip destructive validation actions (for example failing required checks, auto-opening corrective PRs, or auto-creating drift issues from stale snapshots) when canonical data cannot be refreshed, and mark the run as degraded instead of silently passing.
-4. The workflow **SHOULD** open or update a tracking issue when canonical source unavailability persists for more than one consecutive scheduled run.
+4. The workflow **SHOULD** open or update a tracking issue when canonical source unavailability persists through the next scheduled cron trigger after an unavailable run; manually rerun or ad hoc runs do not count toward this consecutive-run threshold.
diff --git a/specs/compiler-threat-detection-compliance/README.md b/specs/compiler-threat-detection-compliance/README.md
new file mode 100644
index 00000000000..60d41805d9b
--- /dev/null
+++ b/specs/compiler-threat-detection-compliance/README.md
@@ -0,0 +1,31 @@
+# Compiler Threat Detection Compliance Map
+
+This directory maps the threat-detection rule catalog in the [Compiler Threat Detection Specification](../compiler-threat-detection-spec.md#8-compliance-testing) to its conformance test IDs. Each active `CTR-*` rule has one required `T-CTR-*` test ID.
+
+| Rule ID | Test ID |
+|---------|---------|
+| CTR-001 | T-CTR-001 |
+| CTR-002 | T-CTR-002 |
+| CTR-003 | T-CTR-003 |
+| CTR-004 | T-CTR-004 |
+| CTR-005 | T-CTR-005 |
+| CTR-006 | T-CTR-006 |
+| CTR-007 | T-CTR-007 |
+| CTR-008 | T-CTR-008 |
+| CTR-009 | T-CTR-009 |
+| CTR-010 | T-CTR-010 |
+| CTR-011 | T-CTR-011 |
+| CTR-012 | T-CTR-012 |
+| CTR-013 | T-CTR-013 |
+| CTR-014 | T-CTR-014 |
+| CTR-015 | T-CTR-015 |
+| CTR-016 | T-CTR-016 |
+| CTR-017 | T-CTR-017 |
+| CTR-018 | T-CTR-018 |
+| CTR-019 | T-CTR-019 |
+| CTR-020 | T-CTR-020 |
+| CTR-021 | T-CTR-021 |
+| CTR-022 | T-CTR-022 |
+| CTR-023 | T-CTR-023 |
+
+The test triggers, expected compiler actions, and stable diagnostics are defined in [Section 8.1](../compiler-threat-detection-spec.md#81-test-id-catalog). The implementation and concrete test-file mappings are defined in [Section 7.1](../compiler-threat-detection-spec.md#71-baseline-rule-mapping).
diff --git a/specs/compiler-threat-detection-spec.md b/specs/compiler-threat-detection-spec.md
index 88452ac134c..cb81a4f21b0 100644
--- a/specs/compiler-threat-detection-spec.md
+++ b/specs/compiler-threat-detection-spec.md
@@ -7,7 +7,7 @@ sidebar:
# GitHub Actions Compiler Threat Detection Specification
-**Version**: 1.0.20
+**Version**: 1.0.21
**Status**: Candidate Recommendation
**Latest Version**: https://github.com/github/gh-aw/blob/main/specs/compiler-threat-detection-spec.md
**Editors**: GitHub Next (GitHub, Inc.)
@@ -78,12 +78,13 @@ This section anchors the specification version to the minimum gh-aw binary versi
| Spec version | Minimum gh-aw binary version | Lock-file compatibility notes |
|--------------|------------------------------|-------------------------------|
+| `1.0.21` | `v0.83.6` (or newer) | Editorial correction: the Deprecation Policy subsection is numbered 5.4 to match its parent section; no lock-file compatibility changes. |
| `1.0.20` | `v0.83.6` (or newer) | Threat-detection behavior must remain compatible with current `.lock.yml` compilation semantics, including manifest drift enforcement (`gh-aw-manifest` checks for CTR-016), update-check validation (`check-for-updates` handling for CTR-018), cache-memory integrity enforcement (`update_cache_memory` gating for CTR-019), conditional import rejection (`imports.if` rejection for CTR-020), `workflow_run` trigger branch scope enforcement (CTR-021), git subprocess argument-injection guards for remote import/download ref and path arguments (CTR-022), and bash command allowlist illusion rejection for engines lacking allowlist enforcement (CTR-023). No `.lock.yml` schema changes are introduced by CTR-022 or CTR-023; both are compile-time-only validations. |
| `1.0.15`–`1.0.19` | `v0.72.1` (or newer) | Adds `workflow_run` trigger branch-scope enforcement (CTR-021); runtime-only `docker-sbx`, credential-refresh, and Playwright changes introduce no `.lock.yml` schema constraint. |
| `1.0.8`–`1.0.14` baseline | `v0.72.1` (or newer) | Establishes manifest drift (CTR-016), update-check (CTR-018), cache-memory integrity (CTR-019), and conditional-import (CTR-020) validation. |
Compact changelog: `1.0.8` introduced CTR-016 and CTR-018; `1.0.10`–`1.0.13` added
CTR-019; `1.0.14` added CTR-020; `1.0.15` added CTR-021; and `1.0.20` added CTR-022
-and CTR-023. Versions with no distinct lock-file impact are grouped above.
+and CTR-023; `1.0.21` corrects the Deprecation Policy subsection numbering. Versions with no distinct lock-file impact are grouped above.
When this specification version changes, maintainers MUST update this table in the same pull request as any lock-file compatibility changes.
@@ -166,7 +167,7 @@ When a new threat class is identified:
- If implementation already covers the threat, the threat MUST be added to this specification with mapping and tests.
- If implementation does not cover the threat, detection/remediation MUST be implemented and then added to this specification.
-#### 4.3.1 Deprecation Policy
+#### 5.4 Deprecation Policy
When a compiler feature that a `CTR-*` rule depends on is removed, the rule MUST be formally retired:
@@ -386,6 +387,10 @@ The following test IDs map one-to-one to the CTR rules in Section 5.1. Each test
## 10. Change Log
+### 1.0.21 (2026-08-14)
+
+- Corrected the Deprecation Policy subsection number from 4.3.1 to 5.4 so that it matches Section 5, Normative Rule Requirements.
+
### 1.0.20 (2026-08-03)
- Added CTR-022 Git Subprocess Argument Injection (already implemented: `ValidateGitRef`/`ValidateGitPath` in `pkg/gitutil/gitutil.go` reject `ref`/`path` values beginning with `-`, containing NUL bytes or `..`, or absolute paths, before they are passed as positional arguments to `git` subprocesses in `pkg/cli/download_workflow.go`, `pkg/parser/remote_resolve_sha.go`, `pkg/parser/remote_workflow_spec.go`, `pkg/parser/remote_download_file.go`, and `pkg/parser/import_remote.go`; fixed upstream in commit 85d757b6 as CWE-88 remediation for the `git archive` fallback path, then confirmed already applied consistently across all other git subprocess call sites during this audit)
diff --git a/specs/safe-outputs-scratchpad-removal.md b/specs/safe-outputs-scratchpad-removal.md
new file mode 100644
index 00000000000..a3e93773531
--- /dev/null
+++ b/specs/safe-outputs-scratchpad-removal.md
@@ -0,0 +1,9 @@
+# Safe Outputs Scratchpad Removal Checklist
+
+The deprecated [`scratchpad/safe-outputs-specification.md`](../scratchpad/safe-outputs-specification.md) must be removed on or before **2026-09-21**. The canonical specification is [`docs/src/content/docs/specs/safe-outputs-specification.md`](../docs/src/content/docs/specs/safe-outputs-specification.md).
+
+## Removal checklist
+
+- [ ] Before 2026-09-21, replace references to the deprecated scratchpad specification in doc-site navigation, workflow files, and internal links with the canonical specification.
+- [ ] On or before 2026-09-21, delete `scratchpad/safe-outputs-specification.md`.
+- [ ] Verify that no remaining repository references resolve to the deleted scratchpad path.