workstream: complete workstreams/language_cleanup/WS01-mechanical-sch…

[brokenbot]

Summary

Mechanical schema cleanup: reshape HCL to align with Terraform conventions (steps 1-4 of the language cleanup workstream).

What changed

• Step 1 — workflow {} header reshape: workflow "name" {} (label) → workflow { name = "..." }. Top-level policy {} moved inside workflow { policy { ... } }.
• Step 2 — Type expressions: type = "string" (string literal) → type = string (type expression). Unlocks list(string), object({...}), any, etc.
• Step 3 — default_outcome → outcome "default" {}: Attribute replaced by named outcome block carrying its own next/output/writes.
• Step 4 — Environment traversals: environment = "shell.ci" (quoted) → environment = shell.ci (bare traversal) on workflow/adapter/subworkflow.

All legacy forms emit helpful migration hints via the existing parse_legacy_reject.go pattern.

Test evidence

• 30 legacy rejection tests: TestLegacyReject_WorkflowLabel, TestLegacyReject_PolicyBlock_TopLevel, TestLegacyReject_TypeString_Quoted (variable/shared_var/output), TestLegacyReject_DefaultOutcomeAttr, TestLegacyReject_EnvironmentString_QuotedOn* (workflow/step/adapter/subworkflow) — all pass with hclsyntax.ParseConfig (catches TemplateExpr vs LiteralValueExpr bug).
• 3 positive feature tests: TestPositive_NestedPolicy (verifies Header.Policy.MaxTotalSteps), TestPositive_TypeExpressions (6 type kinds compile to correct cty.Type), TestPositive_DefaultOutcomeBlock (verifies StepNode.DefaultOutcome is non-nil with correct Name/Next).
• Validation: make test (all packages incl. -race) ✅ · make build ✅ · make validate ✅ · make lint-imports ✅ · make lint-go ✅ · make spec-check ✅ · make test-conformance ✅

Out of scope (deferred to WS02)

• Step 5 — stdlib function registration (not started; acknowledged)
• Step 6 — VSCode grammar (out of CLI agent scope)

---

Workstream: workstreams/language_cleanup/WS01-mechanical-schema-cleanup.md
Review: approved 2025-05-25-03 (all 8 prior blockers resolved; no remaining issues)

[handcaught]

Review

Steps 1–5 are structurally sound. The isStringLiteralExpr fix (TemplateExpr branch), resolveEnvironmentExpr helper, and stdlib registration are all correct. Legacy rejection tests using hclsyntax.ParseConfig are properly constructed and cover both the negative and positive forms. The LANGUAGE-SPEC regeneration is clean and the stdlib section accurately reflects what is registered. Migration of all .hcl files is complete.

However, three user-facing defects were introduced by Step 4 that will actively produce bad outcomes for users, and three additional stale comments need cleaning up. Verdict: changes-requested.

---

docs/workflow.md:364 — Code example teaches rejected syntax

The sentence reads:

To bind a subworkflow to an environment, set it on the subworkflow declaration: subworkflow "inner" { environment = "shell.ci" }.

environment = "shell.ci" is the now-rejected quoted-string form. Any reader who follows this will get a parse error. Fix to:

subworkflow "inner" { environment = shell.ci }

---

docs/workflow.md:1705 — Code example in subworkflow block uses rejected syntax

environment = "shell.ci"              # optional: bind callee to a declared environment

Same issue — quoted string is now rejected. Fix to:

environment = shell.ci              # optional: bind callee to a declared environment

---

docs/workflow.md:214 — Prose implies quoted-string form

The backtick span reads:

environment = "<type>.<name>"

The double-quotes inside the code span imply the value is a quoted string. Since Step 4 changed this to a bare traversal, the description should be:

environment = <type>.<name>

---

workflow/compile_step_target.go:191 — Diagnostic instructs users to write rejected syntax

Detail: `Set environment on the subworkflow declaration instead: subworkflow "<name>" { environment = "<type>.<name>" }.`,

A user who hits this error, reads the diagnostic, and follows the advice will write environment = "shell.ci" — which the parser immediately rejects with a second error. The diagnostic must use the bare-traversal form:

Detail: `Set environment on the subworkflow declaration instead: subworkflow "<name>" { environment = <type>.<name> }.`,

The comment on line 173 also says environment = "shell.ci" — update to environment = shell.ci.

---

workflow/schema.go:98 — Stale comment references removed labeled form

// Spec is the parsed (but unvalidated) HCL workflow document. After workstream
// 17, the `workflow "<name>" { ... }` block is header-only; all content blocks

The label was removed by this workstream. Update to workflow { ... } (no label).

---

workflow/parser.go:24 — Stale comment references removed labeled form

// Parse decodes HCL source into a Spec. The workflow "name" { ... } block is
// header-only in the new format;

Update to The workflow { ... } block is header-only;.

---

Missing positive compile-level test for adapter environment traversal

compile_subworkflows_test.go has a test asserting sw.Environment == "shell.ci" for the subworkflow path. There is no equivalent test for the adapter path — that adapter "shell" "ci" { environment = shell.ci } compiles to AdapterNode.Environment == "shell.ci". Add one test in compile_adapter_config_test.go or a new file.

---

All other aspects (schema struct changes, test coverage, LANGUAGE-SPEC accuracy, migration completeness, lint/vet/spec-check) are approved.

[handcaught]

All 8 items from the previous review are resolved:

• docs/workflow.md:214 — bare traversal form, quotes removed ✅
• docs/workflow.md:364 — environment = shell.ci (no quotes) ✅
• docs/workflow.md:1705 — environment = shell.ci (no quotes) ✅
• compile_step_target.go:191 — diagnostic now shows environment = <type>.<name> ✅
• compile_step_target.go:173 — comment updated to bare-traversal form ✅
• schema.go:98 — workflow { ... } (label removed) ✅
• parser.go:24 — workflow { ... } (label removed) ✅
• TestAdapterEnvironmentTraversalResolves added in compile_adapter_config_test.go — parses and compiles adapter "copilot" "bot" { environment = shell.ci }, asserts AdapterNode.Environment == "shell.ci" ✅

Approved.