diff --git a/docs/briefs/r3-substrate-t-workflow-as-data-canvas.md b/docs/briefs/r3-substrate-t-workflow-as-data-canvas.md deleted file mode 100644 index 69cbf5f039e..00000000000 --- a/docs/briefs/r3-substrate-t-workflow-as-data-canvas.md +++ /dev/null @@ -1,77 +0,0 @@ -# Canvas — Substrate T-Workflow-As-Data carriers (5-row scope-narrowing) - -**Sub-issue**: gunbc#1956 (T-Workflow-As-Data CI-workflow-as-.dag-data demo, parented under #1939); umbrella scope is §10.3 row Q-Workflow-As-Data-Carriers (line 983, OPEN — Substrate Mgr scoping needed). -**Authority**: `docs/r3-program-plan.md:474-480` (5 carrier names) + `docs/r3-design-schedule-2026-05-06.md:84-88` (audit-first directive); `dsl/extdeps/github/actions.dag` (218 lines, already-substrate); audit-and-delta receipt landed 2026-05-06 via #1771 (closed #1873). -**Closure predicate**: §1.8 gates #53 (workflow_substrate_carriers_landed), #54 (timing_lens_carrier_landed), #55 (shared_external_attachment_pattern_documented), #56 (ci_workflow_modeled_as_dag), #62 (substrate_gap_file_ingestion_closed), #63 (substrate_gap_workflow_scheduling_closed). -**Status**: **canvas — Director-tier ratification needed on reuse-vs-new scope before worker brief authoring**. - -## Observation: 4 of 5 named carriers ALREADY exist in `extdeps.github.actions` - -Per §S4 design-schedule directive line 84 (codex BLOCKING 2026-05-06): "S4 worker brief MUST audit `extdeps.github.actions` first and either (a) extend/refine existing carriers via T-Workflow-As-Data lens-consumption-shape additions (preferred per `feedback_audit_adjacent_authority_first` + `feedback_parallel_representation_debt`), or (b) explicitly dissolve `extdeps.github.actions` with a migration path before introducing parallel carriers." - -Grep-verified `dsl/extdeps/github/actions.dag` at HEAD: - -| §10.3 row 983 carrier name | extdeps.github.actions HEAD | Reuse/refine | Net new substrate | -|---|---|---|---| -| `WorkflowTrigger` (Push / PullRequest / Cron / Manual) | `WorkflowTrigger` (Push / PullRequest / Schedule / WorkflowDispatch / WorkflowCall) at `:40` | Refine: `Schedule { cron: String }` → typed `Cron` carrier (per design-schedule:87) | minimal | -| `WorkflowStep` (run command + dependencies + outputs) | `Step` at `:103` | Reuse name `Step`; lens-consumption may add observation anchor | none if pure reuse | -| `WorkflowMatrix` (parameter expansion) | `MatrixStrategy` at `:66+` (inside `Job`) | Reuse + possibly extract as standalone carrier for lens consumption | minimal | -| `WorkflowSecret` (provider-typed, opaque-at-rest, scoped-by-step) | NOT EXTANT in actions.dag at HEAD | **NEW substrate** | full carrier | -| `RunnerResource` (compute class, OS, hardware) | `RunnerSpec` + `RunnerLabel` at `:88+` | Reuse + parameterize as `RunnerResource` for lens-shape consumption | minimal | -| `Workflow` composing carrier | `Workflow` at `:20` (untyped composition) | Refine to parameterized form for lens generic dispatch | minimal | - -**Key finding**: of the 5 named carriers in §10.3 row 983, **only `WorkflowSecret` is wholly new substrate**. The other 4 are reuse-or-refine of existing `extdeps.github.actions` types. The audit-and-delta receipt (#1771, closed via #1873) confirmed this shape; the canvas territory now is **the lens-consumption-shape question**, NOT a 5-carrier-introduction question. - -## Real canvas question (post-audit) - -Given the existing `extdeps.github.actions` substrate is the reuse-base, what's the **minimum additional substrate** needed for T-Workflow-As-Data closure? - -### Option α — Maximalist: introduce all 5 named carriers in `dsl/std/workflow.dag` as parametric refinements - -New file `dsl/std/workflow.dag` declares parameterized versions of all 5 carriers; `extdeps.github.actions` types become specialized instances via composition. New `WorkflowSecret` lands here. - -**Pro**: clean substrate-internal home for T-Workflow-As-Data; lens consumption talks to `dsl/std/workflow.dag` (compiler-internal vocabulary), not `dsl/extdeps/github/` (external-tool vocabulary). -**Con**: introduces parallel-representation debt with `extdeps.github.actions` (per `feedback_parallel_representation_debt`). The audit-receipt's reuse-first directive argues against this. 5 new types when only 1 is wholly novel. - -### Option β — Minimalist (audit-receipt-honoring): land only `WorkflowSecret` + `Cron` refinement; lens consumes existing `extdeps.github.actions` types directly - -Single new file `dsl/std/workflow_secret.dag` (or fold into `extdeps.github.actions` if scope-cohering) carrying `WorkflowSecret` + the typed `Cron` refinement. Lens-consumption shapes (e.g., `WorkflowObservationAnchor`) land in `dsl/std/workflow.dag` separately if/when needed by the lens; T-Workflow-As-Data's CI-workflow-as-.dag-data demo (#1956) consumes the refined `extdeps.github.actions` directly. - -**Pro**: minimal substrate addition; honors audit-receipt's reuse-first directive (`feedback_audit_adjacent_authority_first`); single point of new-substrate, single point of refinement. No parallel-representation debt. -**Con**: lens consumption talks to `extdeps.github.actions` (external-tool vocabulary) — may look conceptually inconsistent with other lens consumers reading `dsl/std/*` types. Mitigation: documented as deliberate audit-receipt outcome. - -### Option γ — Lens-consumption-shape carrier separately + minimal new substrate - -Like β but with `WorkflowObservationAnchor` (per Substrate Mgr design stance at gunbc#1130 comment-4374109666) explicitly authored alongside `WorkflowSecret`. The lens-consumption layer is its own typed carrier; doesn't conflate with `extdeps.github.actions` reuse. - -**Pro**: separates "external-tool vocabulary" (extdeps.github.actions, reuse) from "lens-consumption substrate" (new `WorkflowObservationAnchor`); each layer has single concern. Lens consumers read `WorkflowObservationAnchor`, which references `extdeps.github.actions::Workflow` structurally. -**Con**: 2 new substrate carriers vs β's 1; mild scope expansion. Justifiable IF lens-consumption-shape genuinely needs typed handle distinct from `extdeps.github.actions::Workflow`. - -## Mgr-tier recommendation - -Provisional **β** (minimalist, audit-receipt-honoring): only `WorkflowSecret` + `Cron` refinement land as net-new substrate. Lens consumes `extdeps.github.actions` directly until evidence shows a typed lens-handle is needed. **γ** is the natural ratchet from β if lens-consumption-shape evidence accumulates (per `feedback_construction_over_ratchets` — model first, dissolve later if substrate evidence forces). - -**α rejected** — admits parallel-representation debt against `extdeps.github.actions` audit-receipt findings. - -## Director ratification ask - -1. **Pick α / β / γ** (or surface fourth). Mgr recommendation: **β**. -2. Confirm `extdeps.github.actions` audit-receipt at #1771 is the binding precedent for reuse-first posture (i.e., the audit confirmed reuse is the right shape, not deprecation). -3. Confirm `WorkflowSecret` location: `dsl/std/workflow_secret.dag` (new file) vs fold into existing `extdeps.github.actions` (extension). Provisional Mgr preference: **new file** (compiler-internal substrate, distinct from external-tool vocabulary; honors layer model). -4. Confirm whether §1.8 gate #54 (`timing_lens_carrier_landed`) and gate #55 (`shared_external_attachment_pattern_documented`) are in T-Workflow-As-Data scope or fold to T-LBP / separate sub-lane. - -## On ratification — worker brief scope - -Will author execution brief covering: -- `WorkflowSecret` carrier (`dsl/std/workflow_secret.dag` per option β/γ) -- `Cron` typed refinement (location TBD per question 3) -- (γ only) `WorkflowObservationAnchor` lens-consumption-shape carrier -- Worker pin: substrate-fact-introduction precedent owners (valiant-ibex-312 / smart-ram-167) -- Acceptance: §1.8 gates #53-#56 + #62-#63 advance per closure-predicate scope -- T-Workflow-As-Data #1956 demo consumer wiring (CI-workflow-as-.dag-data) in same-slice or cross-Mgr handoff per Director ratification - -## Sequencing caveat - -Per §S4 design-schedule line 95: "post-T-Lens-Behavioral-Parity COMPLETE (per `r3-structure.md` §"Dependency on R2"; lens consumption needs lenses COMPLETE)". This canvas is dispatch-ready post-T-LBP COMPLETE; brief authoring can land in advance per pre-staging discipline but worker dispatch waits. - -— Authored by warm-wolf-698 (Substrate Mgr) 2026-05-07 post-#2105 merge per Director endorsement of pre-staging next-up substrate canvases. Honors audit-and-delta receipt #1771 (closed #1873) reuse-first directive. diff --git a/docs/briefs/r3-substrate-t-workflow-as-data-slice-1-worker.md b/docs/briefs/r3-substrate-t-workflow-as-data-slice-1-worker.md new file mode 100644 index 00000000000..f7fd48060ad --- /dev/null +++ b/docs/briefs/r3-substrate-t-workflow-as-data-slice-1-worker.md @@ -0,0 +1,100 @@ +# Worker brief — Substrate T-Workflow-As-Data Slice 1 (β ratified) + +**Sub-issue**: parent #1956 (T-WAD CI-workflow-as-.dag-data demo) eventually consumes; PM authors a Slice-1-specific work-item under #1939 post-this-brief landing. +**Authority**: Director ratification of **option β** at gunbc#828 #issuecomment-4395945465 (2026-05-07); 4 asks confirmed (β / #1771 audit-receipt binding / WorkflowSecret folds into extdeps / slice 2-3 separate canvases). +**Closure predicate**: §1.8 gate #53 `workflow_substrate_carriers_landed` (this slice) + #62 `substrate_gap_file_ingestion_closed` + #63 `substrate_gap_workflow_scheduling_closed` (per T-Workflow-As-Data lane row scope). + +## Slice scope (binding per Director) + +T-Workflow-As-Data is split into 3 sub-slices per Director ratification ask #4: +- **Slice 1 (this brief)** — workflow substrate carriers (β minimalist) +- **Slice 2** — timing-and-pattern (TimingMeasurement + TimingObservationSet + WorkflowObservationAnchor + TimingBudget; gates #54 #55) — SEPARATE canvas, gated on T-LBP COMPLETE per §S4 design-schedule:95 +- **Slice 3** — `ci_workflow_modeled_as_dag` demonstration (gate #56) — SEPARATE canvas, consumes slices 1+2 + +**Slice 1 net-new substrate** (only what was identified as wholly novel in the canvas): +1. `WorkflowSecret` carrier — provider-typed, opaque-at-rest, scoped-by-step +2. `Cron` typed refinement of existing `WorkflowTrigger::Schedule { cron: String }` (currently String; refine to typed cron expression) + +Out-of-slice for the 4 reuse-named carriers (per audit #1771): +- `WorkflowTrigger` already at `dsl/extdeps/github/actions.dag:40` (only the inner `Schedule { cron: String }` refines to `Cron` shape per #2 above; outer `WorkflowTrigger` enum unchanged) +- `Step` (=`WorkflowStep`) at `:103`, `MatrixStrategy` (=`WorkflowMatrix`) inside `Job` at `:66+`, `RunnerSpec`+`RunnerLabel` (=`RunnerResource`) at `:88+`, `Workflow` at `:20` — all reused as-is; lens consumes existing types directly per `feedback_audit_adjacent_authority_first` + +## Carrier shape (binding per Director ask #3) + +**Location**: `dsl/extdeps/github/actions.dag` — fold-into-extdeps, NOT new `dsl/std/` file. Per Director rationale: all sibling carriers already live there + secret management IS provider-specific (GitHub Secrets, GitLab Variables, AWS Secrets Manager, etc.) — putting `WorkflowSecret` in `dsl/std/` would imply cross-provider universality that doesn't exist at HEAD. + +**`WorkflowSecret`**: + +```dag +// Opaque-at-rest secret reference scoped by step. Name parameter carries the +// provider-side secret identifier (e.g., "GITHUB_TOKEN", "ANTHROPIC_API_KEY") +// without exposing the secret value at substrate level. Resolution happens at +// workflow-execution time via the provider's secret store. +type WorkflowSecret { + name: Name // typed identifier (provider-scoped) + scope: SecretScope // step-level vs job-level vs workflow-level +} + +type SecretScope = StepScope | JobScope | WorkflowScope +``` + +**`Cron`** typed refinement at `dsl/extdeps/github/actions.dag:43`: + +```dag +// Refines WorkflowTrigger::Schedule { cron: String } to typed cron carrier. +// Cron expression is structured (minute / hour / day-of-month / month / day-of-week) +// rather than opaque-string; fail-closed on parse errors at fixture load. +type CronExpression { + minute: CronField + hour: CronField + day_of_month: CronField + month: CronField + day_of_week: CronField +} + +type CronField = Wildcard | Exact(Int) | List(List) | Range(Int, Int) | Step(Int, Int) + +// WorkflowTrigger update: replace inner Schedule { cron: String } with typed Cron. +type WorkflowTrigger + = ... // existing variants unchanged + | Schedule { cron: CronExpression } // typed (was: String) + | ... +``` + +**STOP-and-PING the Mgr** if `CronExpression` decomposes into more than 5 fields (e.g., year support or seconds support emerges as needed) — that's substrate-shape expansion warranting Director ratification. + +### Cross-provider scope question (Director ratification ask #3 caveat) + +Per Director: "if your lane visibility shows evidence the carrier is intended cross-provider (e.g., Anthropic provider work uses same shape), surface and we can elevate to `dsl/std/`. Default is fold-into-extdeps; promote-to-std only when cross-provider evidence accumulates." + +Worker greps the codebase + adjacent provider work (Anthropic, OpenAI per `dsl/extdeps/llm/`) for `WorkflowSecret`-shaped patterns BEFORE folding. If cross-provider evidence emerges, **STOP-and-PING the Mgr**; otherwise proceed with fold-into-extdeps. + +## Acceptance gates (same-slice, all must pass) + +1. `WorkflowSecret` + `SecretScope` carriers landed in `dsl/extdeps/github/actions.dag`. +2. `CronExpression` + `CronField` carriers landed in `dsl/extdeps/github/actions.dag`; existing `WorkflowTrigger::Schedule { cron: String }` migrated to `Schedule { cron: CronExpression }` with fixture-load fail-closed parse semantics. +3. **No parallel-representation**: verify via grep that `dsl/std/` does NOT contain `WorkflowSecret`, `CronExpression`, or sibling shapes (would indicate accidental general-substrate creation against Director ratification). +4. §1.8 gates advance: #53 `workflow_substrate_carriers_landed` → CONSUMER_LANDED; #62 `substrate_gap_file_ingestion_closed` + #63 `substrate_gap_workflow_scheduling_closed` advance per closure predicate. +5. Bootstrap regen: `cargo test -p v3-compiler bootstrap_regen_fresh -- --ignored` clean. +6. Full suite: `cargo test --workspace --exclude v2-compiler-tests` green; `cargo clippy --all-targets -- -D warnings` clean. + +## STOP / PING criteria + +- **STOP** if cross-provider evidence emerges for `WorkflowSecret` shape (per Director ask #3 caveat) — surface to Mgr; promote-to-`dsl/std/` requires Director re-ratification. +- **STOP** if `CronExpression` field-count expands beyond 5 (e.g., year / seconds / nanoseconds) — substrate-shape expansion warrants Director ratification. +- **STOP** if migration of existing `WorkflowTrigger::Schedule { cron: String }` cascades into emit/typecheck surfaces beyond actions.dag — surface scope-creep. +- **PING** Verification Mgr (#2075) at PR-open time so they can advance §1.8 gates #53/#62/#63 ratchet authoring per standing concern. + +## Sequencing + +Per §S4 design-schedule:95: Slice 1 dispatch-ready post-T-LBP COMPLETE (lens consumption needs lenses COMPLETE). Brief authoring lands in advance per pre-staging discipline. Slice 2 + Slice 3 are SEPARATE canvases authored when their preconditions clear (slice 2 gates on T-LBP COMPLETE; slice 3 consumes 1+2). + +## Worker pin (Mgr disposition) + +valiant-ibex-312 OR smart-ram-167 (substrate-fact-introduction precedent owners). Final pin at dispatch. + +## Auto-spawn caveat + +Per Director's standing note + cache-staleness cluster ctrl#217: HOLD dispatch on this brief until auto-spawn fix lands per L-sized substrate-fact-introduction threshold. + +— Authored by warm-wolf-698 (Substrate Mgr) 2026-05-07 per Director β-ratification at gunbc#828 #issuecomment-4395945465.