[awf-feature-surfacing] AWF surfacing gaps: conditional `if:` imports, `dangerously-disable-sandbox-agent` flag, and `create_issue` body minLength

[github-actions]

This is an automated AWF spec/compiler surfacing review (first run; 7-day window ending at 550af45). Three newly-introduced AWF capabilities/constraints are not yet surfaced in gh-aw docs or migration guidance. The sandbox one is the most urgent because the upgrade guide actively recommends a pattern that now fails compilation.

1. Conditional if: on imports (High)

A new if: property was added to import entries in main_workflow_schema.json (all 4 import variants: imports[] object form, imports[].with, and the nested uses object/with forms). It guards an entire import at runtime using experiments.<name> expressions (e.g. if: "experiments.strategy == 'eager'"). Steps and prompt content from the import are only active when the condition is true.

Surfacing status: Not documented. The object-form import field list in .github/aw/syntax-tools-imports.md (around lines 250-276) documents checkout:, env:, with:/inputs: but not if:. .github/aw/reuse.md has no if: on imports. .github/aw/experiments.md only warns against nesting {{#if experiments.<name> }} inside {{#runtime-import? }} blocks (line 314) — the new if: field is precisely the supported alternative for experiment-gating an import, so the warning now needs a pointer to it.

Tasks:

• (High) Document if: in the import object-form field list in syntax-tools-imports.md, including the experiments.<name> form and runtime-gating semantics.
• (Medium) Add an example in reuse.md and cross-link from experiments.md line ~314 (replace/augment the anti-nesting warning with the if: field as the recommended approach).
• (Low) Add a compiler test asserting an import with if: is gated as expected (verify coverage exists in pkg/workflow/).

2. dangerously-disable-sandbox-agent feature flag now required for sandbox.agent: false (High)

Commit 0175f04b6 (#38205) changed pkg/workflow/sandbox_validation.go: previously sandbox.agent: false was allowed in non-strict mode (warning only); now it raises a hard validation error unless the feature flag is set:

features:
  dangerously-disable-sandbox-agent: true
sandbox:
  agent: false

New constant DangerouslyDisableSandboxAgentFeatureFlag in pkg/constants/feature_constants.go.

Surfacing status / migration risk: .github/aw/upgrade-agentic-workflows.md:105 currently advises "Replacing 'network.firewall' with 'sandbox.agent: false'" — following that guidance now produces a compile error. The flag is not mentioned in syntax-agentic.md (features: is listed generically at line 54) nor in the upgrade guide.

Tasks:

• (High) Fix upgrade-agentic-workflows.md:105 to require the dangerously-disable-sandbox-agent feature flag alongside sandbox.agent: false.
• (High) Document the flag and its security rationale in syntax-agentic.md near the sandbox.agent / features: discussion.
• (Medium) Confirm any codemod/upgrade tooling that auto-rewrites network.firewall → sandbox.agent: false also injects the feature flag.

3. create_issue body minLength enforcement (Medium)

Commit 1db57bcf1 (#38114) added minLength: 20 to the create_issue body field in safe_outputs_tools.json (both pkg/workflow/js/ and actions/setup/js/) and the JS/Go validators. Workflows emitting issue bodies shorter than 20 chars now fail validation.

Surfacing status: Not documented in the safe-outputs docs (safe-outputs-content.md, etc.).

Tasks:

• (Medium) Document the 20-character minimum (and existing 65000 max) for create_issue body in the safe-outputs reference docs.
• (Low) Note the constraint in create-agentic-workflow.md / report patterns so generated workflows produce sufficiently long bodies.

Evidence (commits, files, schema keys)

• Schema: pkg/parser/schemas/main_workflow_schema.json — new if: on import entries (4 locations).
• 0175f04b6 — pkg/workflow/sandbox_validation.go, pkg/constants/feature_constants.go (DangerouslyDisableSandboxAgentFeatureFlag).
• 1db57bcf1 — pkg/workflow/js/safe_outputs_tools.json, actions/setup/js/safe_outputs_tools.json (minLength: 20), safe_outputs_validation_config.go, samples_validation.go.
• Docs checked: .github/aw/syntax-tools-imports.md, reuse.md, experiments.md, syntax-agentic.md, upgrade-agentic-workflows.md, safe-outputs-*.md.
• Considered but not actioned: c69bc59cd (dynamic checkout.repository — internal manifest move, marginal surfacing need), 402c2979b (error-hint UX only), plus internal/cosmetic commits (9449a1d18, 12d066797, d1c293e78, 550af45).

Feature IDs (tracked in repo-memory): imports.if-conditional, features.dangerously-disable-sandbox-agent, safe-outputs.create-issue-min-body.

Generated by 🧭 Daily AWF Spec Compiler Surfacing Review · 112.3 AIC · ⌖ 11.9 AIC · ⊞ 4.7K · ◷

• expires on Jun 16, 2026, 2:50 PM UTC-08:00

[rpelevin]

For the sandbox item, I would frame dangerously-disable-sandbox-agent as an authority-boundary change, not just a schema feature flag.

The migration risk is that a workflow author follows the old upgrade guidance and thinks they made a mechanical syntax update, while the actual new state is "this agent no longer has the sandbox boundary."

I would make the docs and compiler surface three facts together:

• requested sandbox state: sandbox.agent: false;
• explicit authority override: features.dangerously-disable-sandbox-agent: true;
• reason / provenance: who or what chose to run this workflow without the agent sandbox.

Concrete acceptance shape:

1. the upgrade guide shows the flag and sandbox.agent: false in the same before/after block.
2. syntax-agentic.md states that the flag disables a trust boundary, not only a validator check.
3. compiler error text says which flag is required and why the default is fail-closed.
4. any codemod that inserts the flag also leaves an auditable migration marker or requires explicit opt-in, so a silent rewrite cannot weaken the sandbox.
5. tests cover both missing-flag rejection and explicit-flag acceptance.

That keeps the dangerous path available for workflows that truly need it, but makes the authority change reviewable instead of hidden inside a successful migration.

[pelikhan]

@copilot refactor features.dangerously-disable-sandbox-agent into a string (minimum 20 characters) that justifies why the sandbox is being disabled. Must be enforced by the compiler. Expressions not allowed

features:
  dangerously-disable-sandbox-agent: controlled environment with no internet access

[rpelevin]

Yes, this is much stronger than a boolean.

Making the feature value the justification keeps the dangerous path explicit at the same place the trust boundary is removed.

I would pin a few acceptance details:

1. empty, short, whitespace-padded, or expression-like values fail compiler validation before the workflow can run.
2. a 20+ character literal reason with sandbox.agent: false passes.
3. true no longer passes as a legacy shorthand.
4. any migration or codemod from network.firewall to sandbox.agent: false cannot silently invent a generic reason; it should require an operator-authored justification or leave a failing/TODO state.
5. the parsed workflow keeps the justification available for docs, diagnostics, and audit/logging, not just validation.

Tests I would add:

1. features.dangerously-disable-sandbox-agent: true fails.
2. ${{ ... }} or other expressions fail.
3. too-short and whitespace-padded strings fail.
4. a literal justification with sandbox.agent: false passes.
5. compiler diagnostics say that disabling the agent sandbox removes a trust boundary and needs a reason.
6. upgrade examples show the string reason beside sandbox.agent: false.

That turns the feature from "disable sandbox" into "disable sandbox with a reviewable reason," which is the right authority boundary.