[caveman] Optimize instruction verbosity — action-container-substitutions, developer.instructions (2026-08-16)

.github/agents/developer.instructions.md

@@ -55,25 +55,7 @@ graph TD
 
 Validates workflow configs before compilation. Centralized in `validation.go`, or domain-specific in dedicated files.
 
-### Validation Flow
-
-```mermaid
-graph TD
-    A[Workflow YAML] --> B[Parser]
-    B --> C[Validation System]
-    C --> D[Centralized Validation]
-    C --> E[Domain-Specific Validation]
-    D --> F[validation.go]
-    E --> G[strict_mode_validation.go]
-    E --> H[pip.go]
-    E --> I[npm.go]
-    F --> J{Valid?}
-    G --> J
-    H --> J
-    I --> J
-    J -->|Yes| K[Compiler]
-    J -->|No| L[Error Report]
-```
+Workflow YAML → parser → validation (centralized + domain-specific) → compiler on pass, error report on fail.
 
 ### Centralized Validation: `pkg/workflow/validation.go`
 
@@ -143,20 +125,6 @@ graph TD
 
 ### Sanitize vs Normalize
 
-```mermaid
-graph TD
-    A[Need String Processing?] --> B{Security Concern?}
-    B -->|Yes| C[Sanitize]
-    B -->|No| D{Consistency Needed?}
-    C --> E[sanitizeGitHubLabel]
-    C --> F[sanitizeGitHubBranch]
-    C --> G[sanitizeGitHubIssueTitle]
-    D -->|Yes| H[Normalize]
-    D -->|No| I[Use As-Is]
-    H --> J[normalizeWhitespace]
-    H --> K[normalizeLineEndings]
-```
-
 **Sanitize** — fix chars that break security or GitHub API:
 - `sanitizeGitHubLabel()` — label requirements (no emoji, length limits)
 - `sanitizeGitHubBranch()` — Git ref rules
@@ -230,17 +198,6 @@ safe_outputs:
 
 ## Custom GitHub Actions
 
-### Architecture
-
-```mermaid
-graph LR
-    MD[Workflow .md] --> Compiler
-    Compiler --> YAML[.lock.yml]
-    YAML --> GHA[GitHub Actions Runner]
-    GHA --> Actions[Custom Actions]
-    Actions --> API[GitHub API]
-```
-
 ### Build System
 
 Go: `pkg/cli/actions_build_command.go`. No JS build scripts.
@@ -335,20 +292,6 @@ make update-golden  # only when intentionally changing output
 
 Persistent, git-backed storage across workflow runs. State lives in dedicated git branches with auto-sync.
 
-### Architecture Overview
-
-```mermaid
-graph TD
-    A[Agent Job Start] --> B[Clone memory/{id} branch]
-    B --> C[Agent reads/writes files]
-    C --> D[Upload artifact: repo-memory-{id}]
-    D --> E[Push Repo Memory Job]
-    E --> F[Download artifact]
-    F --> G[Validate files]
-    G --> H[Commit to memory/{id}]
-    H --> I[Push to repository]
-```
-
 ### Path Conventions
 
 | Pattern | Format | Example | Purpose |
@@ -359,10 +302,10 @@ graph TD
 
 ### Data Flow
 
-1. Clone `memory/{id}` branch
+1. Agent job clones `memory/{id}` branch
 2. Agent reads/writes files
-3. Upload directory as artifact
-4. Download artifact, validate constraints
+3. Upload directory as artifact `repo-memory-{id}`
+4. Push Repo Memory job downloads artifact, validates constraints
 5. Commit and push to `memory/{id}`
 
 ### Key Configuration

.github/aw/action-container-substitutions.md

@@ -26,8 +26,6 @@ These are repository-level settings in `aw.json`, not workflow frontmatter, so o
 - Map each source version individually — no wildcard or prefix matching.
 - The replacement target must itself be resolvable by the pin machinery (dynamic lookup, embedded pins, or local cache); otherwise resolution fails.
 
-One console message per mapped key is logged at compile time.
-
 ## Container substitutions (`container_pins`)
 
 `container_pins` maps source container image references (e.g. `ghcr.io/owner/image:tag`) to replacement targets. Applied before digest-pin resolution, so a mirrored image can replace the public source.
@@ -37,8 +35,8 @@ Each value is an object with separate `image` (ref name) and `digest` (SHA-256)
 ```json title=".github/workflows/aw.json"
 {
   "container_pins": {
-    "ghcr.io/actions/runner:latest": {
-      "image": "registry.acme.com/runner:latest",
+    "ghcr.io/github/gh-aw-firewall:0.27.22": {
+      "image": "registry.acme.com/gh-aw-firewall:0.27.22",
       "digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
     },
     "node:lts-alpine": {
@@ -54,32 +52,11 @@ Each value is an object with separate `image` (ref name) and `digest` (SHA-256)
 - `image` must be a valid reference without a digest component (e.g. `registry.acme.com/image:tag`).
 - `digest` must be a full SHA-256 digest in `sha256:<64 lowercase hex chars>` form.
 
-One console message per mapped key is logged at compile time.
-
-## Combined example
-
-```json title=".github/workflows/aw.json"
-{
-  "action_pins": {
-    "actions/checkout@v4": "acme-corp/checkout-mirror@v4",
-    "actions/setup-node@v4": "acme-corp/setup-node-mirror@v4"
-  },
-  "container_pins": {
-    "ghcr.io/github/gh-aw-firewall:0.27.22": {
-      "image": "registry.acme.com/gh-aw-firewall:0.27.22",
-      "digest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
-    },
-    "node:lts-alpine": {
-      "image": "registry.acme.com/node:lts-alpine",
-      "digest": "sha256:abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
-    }
-  }
-}
-```
+Both keys may be set in the same `aw.json`.
 
 ## Notes
 
 - Substitutions apply at compile time and are baked into the generated `.lock.yml` files.
-- Neither `action_pins` nor `container_pins` works in workflow frontmatter; both are `aw.json` repository-level settings.
+- One console message per mapped key is logged at compile time.
 - Re-run `gh aw compile` after modifying `aw.json`.
 - See [Self-Hosted Runners](/gh-aw/reference/self-hosted-runners/#action-and-container-substitutions-awjson) for full docs.