[docs] Developer docs consolidation v6.8

scratchpad/dev.md

@@ -1,7 +1,7 @@
 # Developer Instructions
 
-**Version**: 6.7
-**Last Updated**: 2026-04-21
+**Version**: 6.8
+**Last Updated**: 2026-04-22
 **Purpose**: Consolidated development guidelines for GitHub Agentic Workflows
 
 This document consolidates specifications from the scratchpad directory into unified developer instructions. It provides architecture patterns, security guidelines, code organization rules, and testing practices.
@@ -1097,8 +1097,9 @@ gh aw <command> [flags] [arguments]
 ```
 
 **Command Categories**:
-- **Workflow Management**: `run`, `compile`, `validate`
+- **Workflow Management**: `run`, `compile`, `validate`, `fix`
 - **Safe Outputs**: `safe-outputs`
+- **Audit**: `audit diff`, `audit report`, `logs`
 - **Utilities**: `version`, `help`
 
 ### Logger Namespace Convention
@@ -1520,6 +1521,20 @@ steps:
 - uses: actions/checkout@v6
 ```
 
+**Pinned Container Images by Digest** (PR #27762):
+
+Builtin container images (such as the CLI proxy and DIFC proxy images) are pinned by SHA-256 digest in compiled lock files and the AWF hash-spec configuration. This ensures reproducible builds and prevents mutable tag drift:
+
+```yaml
+# ✅ Pinned by digest (generated by compiler)
+image: node:lts-alpine@sha256:abc123...
+
+# The compiler resolves mutable tags to immutable digests
+# Original: node:lts-alpine  →  Pinned: node:lts-alpine@sha256:abc123...
+```
+
+The `ContainerPin` struct in `pkg/actionpins` manages this mapping: `Image` (original tag), `Digest` (bare SHA-256), and `PinnedImage` (resolved reference). The action cache stores container pins alongside action pins.
+
 ### Input Validation
 
 **User Input Sanitization**:
@@ -1779,6 +1794,39 @@ The `safe-inputs` feature flag and frontmatter field have been renamed to `mcp-s
 
 Migration: run `gh aw fix` to automatically migrate existing workflows.
 
+**`label_command` trigger** (new in pending release):
+
+Workflows can run when a configured label is added to an issue, pull request, or discussion using the `label_command` trigger. The activation job removes the triggering label at startup and exposes `needs.activation.outputs.label_command` for downstream use.
+
+```yaml
+on:
+  label_command:
+    - "run-analysis"
+    - "triage-me"
+status-comment: true   # Default for label_command triggers
+```
+
+**`status-comment` default for `label_command`**: As with `slash_command`, `status-comment: true` and `reaction: eyes` are now enabled by default when `label_command` is used. Disable explicitly if not needed:
+
+```yaml
+on:
+  label_command: ["run-analysis"]
+  status-comment: false  # Override default
+  reaction: none         # Override default
+```
+
+**GHE Support** (`configure_gh_for_ghe.sh`):
+
+Workflows that call `gh` CLI commands on GitHub Enterprise Server domains should source `configure_gh_for_ghe.sh` before any `gh` calls. The script auto-detects the correct GHE host from environment variables (`GITHUB_SERVER_URL`, `GITHUB_ENTERPRISE_HOST`, `GITHUB_HOST`, or `GH_HOST`):
+
+```bash
+# Source before gh CLI commands in GHE environments
+source /path/to/configure_gh_for_ghe.sh
+gh issue list  # Now targets the correct GHE host
+```
+
+Without this, `gh` commands may fail with "none of the git remotes configured for this repository point to a known GitHub host" on GHE domains.
+
 ### Workflow Size Reduction Strategies
 
 ```mermaid
@@ -2595,6 +2643,10 @@ type Everything interface {
 | `gh aw compile` | Compile to YAML | `gh aw compile workflow.md` |
 | `gh aw validate` | Validate workflow | `gh aw validate workflow.md` |
 | `gh aw safe-outputs` | Test safe outputs | `gh aw safe-outputs --staged` |
+| `gh aw fix` | Run migration codemods | `gh aw fix` |
+| `gh aw audit diff <run1> <run2>` | Compare firewall behavior across runs | `gh aw audit diff 12345 67890` |
+| `gh aw audit report` | Cross-run security audit report | `gh aw audit report --format markdown` |
+| `gh aw logs` | Retrieve workflow run logs | `gh aw logs 12345` |
 
 ---
 
@@ -2880,6 +2932,7 @@ These files are loaded automatically by compatible AI tools (e.g., GitHub Copilo
 ---
 
 **Document History**:
+- v6.8 (2026-04-22): Maintenance tone scan — 0 tone issues found. Documented 4 new features from pending changesets: (1) `label_command` trigger with `status-comment: true` and `reaction: eyes` defaults; (2) GHE support via `configure_gh_for_ghe.sh`; (3) `gh aw audit diff` and `gh aw audit report` commands added to CLI quick reference and Command Categories; (4) container image pinning by digest (PR #27762: `ContainerPin` struct in `pkg/actionpins`, compiler resolves mutable tags to immutable SHA-256 digests). Coverage: 64 spec files (no new files).
 - v6.7 (2026-04-21): Maintenance tone scan — 0 tone issues found. Added Agent Output Metrics section documenting OTLP conclusion span attributes emitted from `agent_output.json` (PR #27495: metrics now emitted on all outcomes including failures and timeouts; new attributes: `gh-aw.error.count`, `gh-aw.error.messages`, `gh-aw.output.item_count`, `gh-aw.output.item_types`). Coverage: 64 spec files (no new files).
 - v6.6 (2026-04-20): Maintenance tone scan — 0 tone issues found across all scratchpad files. Added end-to-end feature testing description to Testing Guidelines section linking to `end-to-end-feature-testing.md`. Coverage: 64 spec files (no new files).
 - v6.5 (2026-04-19): Maintenance tone scan — 0 tone issues found. Documented 2 breaking changes from pending changesets: (1) `app:` → `github-app:` rename (breaking: workflows using `app:` fail validation; migrate with `gh aw fix`); (2) `safe-inputs` → `mcp-scripts` rename (feature flag `SafeInputsFeatureFlag` → `MCPScriptsFeatureFlag`; migrate with `gh aw fix`). Updated Go Type Patterns table: `SafeInputsFeatureFlag` → `MCPScriptsFeatureFlag`. Coverage: 64 spec files (no new files).