Vibecoding State

Vibecoding State — Workshop Runtime Contract

This skill is the single source of truth for how every prompt in the repo-root Instructions.md workshop and its worked instantiations (e.g. example/skyloyalty/WALKTHROUGH.md) interacts with the shared per-user state file and the async per-prompt retrospective file.

Prompts do not re-state the "Vibecoding state contract / Preamble / Postamble / Pathway Applicability guard / Retrospective contract" prose. They invoke this skill with typed parameters and this skill owns the behavior.

When to Use

Invoke this skill — always — when executing any vibecoding workshop prompt. Specifically:

• Every prompt in Instructions.md (Prompt 0.1 through 8.24).
• Every prompt in example/<use_case>/WALKTHROUGH.md (e.g. SkyLoyalty's 22 prompts).
• Every post-workshop per-prompt retro + the single session rollup.

Do not invoke for: one-off terminal commands, ad-hoc debugging, or anything outside the workshop flow.

Candidate future skills that this skill deliberately does not absorb (they stay inline in prompts for now): workspace-preflight (databricks compute-policies list, databricks current-user me), llm-endpoint-health (databricks serving-endpoints get <endpoint>), bundle-deploy (databricks bundle validate/deploy/run), derive-app-name (email + use_case_slug → APP_NAME), prd-reader. If you end up duplicating any of those across prompts, extract them next.

Operations

All thirteen operations take a typed parameter bag. The prompt invokes the operation by name (e.g. vibecoding-state.enter) and passes only the dynamic values. Everything else (file paths, log schema, gate rules, pathway matrix, resolved spec) is owned by this skill.

Operation: bootstrap

When: Once per workshop run, at Prompt 0.1 (Instructions.md) or Prompt 1 (WALKTHROUGH.md). Only runs if no live state file exists.

Inputs:

Behavior:

0. Detect environment & write the ## Environment Capabilities block (RULE_0 / RULE_1 enabling). Before any other step, resolve the active coding client and write the capability block (schema in references/state-template.md § Environment Capabilities) as section 0 of the state file. This is the block every prompt and the enter / exit operations read to resolve the deploy verb, CLI channel, and state-file root — so no skill or prompt body assumes a local IDE. Detection signal [inference — pending the live Genie Code probe]: if a Databricks-managed CLI channel is present in-session (the runDatabricksCli tool / Genie serverless markers), set client_context: genie_code, cli_channel: runDatabricksCli, bundle_deploy.page_context_required: true, both state_file_root and artifact_root to the user project workspace path (/Workspace/Users/<email>/<repo> — a git clone of the workshop repo, so it is a git working tree and generated bundles are recognized), and skills_install_root to the skills copy path (/Workspace/Users/<email>/.assistant/skills/<repo>, a copy of the tree for discovery, no git required); otherwise set client_context: ide_cli, cli_channel: local_shell, bundle_deploy.page_context_required: false, and state_file_root, artifact_root, and skills_install_root all to the local repo path. Ensure artifact_root (and thus state_file_root, which equals it) is a git-backed working tree — the kickstart git clones the workshop repo into it; if <artifact_root>/.git is absent, git clone <workshop remote> into it before writing the ## Environment Capabilities block (a bare mkdir leaves generated bundles unrecognized — TESTED; a Repos-managed Git folder is the documented fallback). On genie_code operate via the workspace path / executeCode, mindful of the FUSE create-then-validate gap (clone, then confirm os.path.exists(<artifact_root>/.git) before writing); a non-PRD-first flow may reach bootstrap before the clone exists. (artifact_root defaults equal to state_file_root; it is where relative artifact paths resolve as <ARTIFACT_ROOT>/<relpath> — see skills/genie-code-environment §8. skills_install_root is the read-side anchor: a copy of the clone on genie_code, the same repo on ide_cli.) Also set skill_ref_root — the prefix that makes a repo-relative skill path loadable: on genie_code it is the readSkillFile prefix "skills/" + basename(skills_install_root) (e.g. skills/vibe-coding-workshop, because the skills copy lives under .assistant/skills/<repo> and any file there loads as skills/{path-after-.assistant/skills/}); on ide_cli it is empty (repo-relative skill paths / @-mentions resolve as-is). See skills/genie-code-environment §8 for how prompts use it. Also set dp_bundle_root = <artifact_root>/{user_schema_prefix}_<use_case_slug>_dab (the use_case_slug bootstrap param is available here; {user_schema_prefix} is the SAME username-derived prefix used for the {user_schema_prefix}_bronze/_silver/_gold schemas — companion app on genie_code, authenticated-user derivation on ide_cli, e.g. jane_d) — the self-contained Databricks Asset Bundle project directory the whole data-product pipeline (bronze→silver→gold→semantic) writes its databricks.yml / src/ / resources/ into, and the bundle deploy page-context root on genie_code. The username prefix disambiguates concurrent users in a shared workspace; the bundle name: inside databricks.yml MUST match this prefixed folder name (bundle: { name: {user_schema_prefix}_<use_case_slug>_dab }). It is the same shape on both clients (a dedicated subdir of the repo/clone root, NOT the bare root and NOT inside a read-only framework dir); see skills/genie-code-environment §8. Also set app_root = <artifact_root>/<app_name> — the AppKit application track's analog of dp_bundle_root: a TOP-LEVEL sibling of <use_case_slug>_dab (NOT nested under apps_lakebase/) that holds the scaffolded app (app.yaml / databricks.yml / server/ / client/ + <app_root>/.vibecoding-state.md) on BOTH clients, so the app's root folder has parity regardless of client. It is the apps init --output-dir target on genie_code, deploys via apps deploy (no bundle page-context pin), and is <pending> until APP_NAME is resolved (Module 1 / prompt 04); n/a for Pathway D. Also set agent_app_root = <artifact_root>/<agent_app_name> — the Track A custom-agent track's analog of app_root: a TOP-LEVEL sibling of <app_name> and <use_case_slug>_dab (NOT nested under apps_lakebase/) that holds the cloned agent framework (app.yaml / pyproject.toml / databricks.yml / server/ + <agent_app_root>/.vibecoding-state.md) on BOTH clients, so the agent app's root folder has parity regardless of client. On genie_code it is the apps init --output-dir target and the uv/FastAPI server builds server-side via apps deploy (mode=SNAPSHOT) — there is no local uv run dev loop. It is <pending> until AGENT_APP_NAME is resolved (Track A clone / prompt 43); n/a for Pathways A/B. The remaining fields are client-invariant: bundle_deploy.verb is always bundle deploy --target dev, app_deploy is always { verb: "apps deploy", gated: true }, and destructive_ops is always confirm_required. Also seed genie_code_manifest_loaded (G3): n/a on ide_cli (the check is inert there), false on genie_code — on Genie Code the first deploy/divergent prompt's enter halts until the skills/genie-code-environment manifest is read in-thread and flips it true (see references/spec-schema.md § Genie Code manifest-load gate). Record the detection signal that fired in a trailing # detected_via: comment so a later live probe can confirm or correct it. For how the detected genie_code client actually behaves — the runDatabricksCli allow-list tiers, the bundle-deploy CWD pin and FUSE create-then-validate gap, the App-scaffold output-dir rule, and the deployed-app OAuth session pattern — see the genie-code-environment skill (this skill detects the client; that skill explains it).
1. Workspace URL normalization & placeholder refusal. Trim any trailing slash from workspace_url and normalize the scheme to https://. Refuse any literal placeholder — <your-workspace-url>, the empty string, or https://<...> — by halting with a remediation hint pointing the operator at Workshop Choices. Record the normalized value in bootstrap_preflight.workspace_url_normalized and the placeholder check in workspace_url_was_placeholder.
2. Profile selection & host match. Run databricks auth profiles and select the profile whose host equals the normalized workspace host. Store it in bootstrap_preflight.workspace_profile. If no profile matches, set workspace_host_auth_status: wrong_host and halt; if the matching profile fails databricks current-user me, set unauthenticated and halt; on success set authenticated.
3. CLI version preflight (client-branched — Gap-1). On ide_cli: capture databricks --version into bootstrap_preflight.databricks_cli_version, compare against bootstrap_preflight.databricks_cli_min_version (default 0.295.0, may be raised by workshop config), and halt with an upgrade hint if the installed version is older. On genie_code: databricks --version is hard-blocked (no local CLI binary — the managed runDatabricksCli channel does not expose a version string; CONFIRMED P1), so set bootstrap_preflight.databricks_cli_version: unknown_on_genie_code and skip the numeric comparison and the version halt entirely. Any later decision that would have keyed off the numeric version (the databricks_cli_min_version registry check, and skill_helper_resolution's CLI-version gate) falls back to the behavior probe — databricks bundle validate accepting the field/deploy without stripping — instead of a version number. The managed channel always tracks a current CLI, so the only real risk a version gate guards against (a stale local install) cannot occur on Genie Code.
4. Apps quota preflight. Before any databricks apps create happens (Pathways A/B/C), run databricks apps list --output json and record current_count, max_count, and free_slots in bootstrap_preflight.apps_quota. If free_slots < 1, halt with a clean-up hint listing the apps the operator can delete.
5. First state file path. Write the bootstrap live file to example/<use_case_slug>/.vibecoding-state.md (used in this repo's example/ examples) or workshops/<use_case_slug>/.vibecoding-state.md (used by external adopters that follow the workshops/ convention). Whichever path is chosen, record it verbatim in bootstrap_preflight.first_state_file_path so migrate_canonical knows exactly which file to move once $APP_NAME is resolved. Set bootstrap_preflight.app_name_known_at_bootstrap = false — $APP_NAME is resolved later by Module 1 / Prompt 2.
6. Copy the template. Copy references/state-template.md to bootstrap_preflight.first_state_file_path.
7. Replace <USE_CASE_SLUG> in the title and both <ISO timestamp> placeholders with the current ISO timestamp.
8. Write all Workshop Choices from the params above.
9. Run databricks auth profiles + databricks current-user me to capture PROFILE, Workspace host, User email into Global Variables. (PROFILE is the same value already stored as bootstrap_preflight.workspace_profile.)
10. Run the serverless-only preflight (databricks compute-policies list) and set workspace_serverless_only.
11. DAB dev-mode schema-prefix detection. If dabs_bundle_path is a real path (not n/a), shell out to databricks bundle validate --target dev --output json from that path and inspect every UC schema resource. If any resource has dev-mode prefixing applied (a name shaped like dev_${user}_<schema> instead of the unprefixed <schema>), set bootstrap_preflight.bundle_dev_mode_schema_prefix_detected = true. Every downstream prompt that passes agent_schema, ops_schema, or uc_schema into a job/notebook MUST read the resolved (prefixed) schema name from state — never the unprefixed variable name.
12. Verify-job summary semantics. Set bootstrap_preflight.verify_summary_semantics from the merged workshop config. Default pass_field/warn_field/fail_field are "pass", "warn", "fail" (matching 05_verify_infrastructure.py's notebook.exit payload). warning_policy defaults to allow_with_notes; set to block_if_load_bearing for use cases whose verify-job emits warnings that must block the gate. When warning_policy == block_if_load_bearing, any warning whose name matches an entry in the workshop's gate_load_bearing_checks[] list blocks the first verify gate (PASS only when fail == 0 AND no load-bearing warning is present).
13. Derive variant_id from pathway + track using the deterministic derivation table in references/resolver-prompt.md § Variant-ID Derivation Table.
14. Invoke resolve_spec (see below) to parse the PRD at prd_path and populate the six spec sections (## Variant, ## Resources, ## UI, ## Agent, ## Governance, ## Spec Provenance). This is a hard step: if resolve_spec halts, bootstrap halts.

Outputs: Path of the bootstrap state file (also stored as bootstrap_preflight.first_state_file_path), populated with ## Environment Capabilities (section 0), ## Bootstrap Preflight, Workshop Choices, Global Variables (partial), and fully resolved Variant / Resources / UI / Agent / Governance / Provenance spec sections (schema v2.0). The workshop continues with this path until migrate_canonical runs.

Errors: If the bootstrap path already exists, abort — do not overwrite. The operator must remove or migrate the stale file. Any of the four halt rules in references/spec-schema.md § Bootstrap Preflight (steps 1–4 above) abort before the template is copied. If resolve_spec fails validation twice, abort and surface the validation errors; the operator must fix the PRD before re-running.

DAB dev-mode schema-prefix rule (consumer-side). If Databricks Asset Bundle dev mode prefixes UC schema resource names, notebook/job parameters must receive the resolved prefixed schema name, not the unprefixed variable. Bootstrap captures bundle_dev_mode_schema_prefix_detected; any prompt that passes agent_schema, ops_schema, or uc_schema to a job reads the resolved value from state.

Operation: resolve_root

When: Any prompt that writes an artifact before bootstrap has run (e.g. the PRD-generation prompt produces docs/design_prd.md before the PRD exists to bootstrap from). It is the minimal, gate-free way to learn where relative artifact paths must land so a bare docs/… does not resolve against a page-dependent CWD on Genie Code. Idempotent — safe to call repeatedly; a later bootstrap supersedes it as the persistence owner.

Inputs: none required. (Optional state_file_path — if the caller already knows where a state file lives.)

Behavior:

1. Read-if-present. If a state file with a ## Environment Capabilities block (section 0) already exists (the live file, or the bootstrap path example/<use_case_slug>/.vibecoding-state.md / workshops/<use_case_slug>/.vibecoding-state.md), read client_context, artifact_root, skills_install_root, and skill_ref_root from it and return them. Do not re-detect or rewrite.
2. Else detect fresh (bootstrap step-0 detection ONLY). Run just the client/root detection from bootstrap step 0 — no URL/profile/CLI/quota preflights, no template copy, no resolve_spec, no gates: if a Databricks-managed CLI channel is present (runDatabricksCli / Genie serverless markers) ⇒ client_context: genie_code, artifact_root = the user project workspace path (e.g. /Workspace/Users/<email>/<repo>, a git clone of the workshop repo), skills_install_root = the skills copy path (e.g. /Workspace/Users/<email>/.assistant/skills/<repo>, a copy for discovery), skill_ref_root = "skills/" + basename(skills_install_root) (e.g. skills/vibe-coding-workshop); otherwise ⇒ client_context: ide_cli, artifact_root = skills_install_root = the local repo root, skill_ref_root = empty.
3. Ensure artifact_root is a git-backed working tree. The kickstart git clones the workshop repo into artifact_root; if <artifact_root>/.git is missing, git clone <workshop remote> into it so the caller's first relative write (e.g. the PRD at <ARTIFACT_ROOT>/docs/design_prd.md, produced before bootstrap) lands in a real, git-backed directory where generated bundles are recognized (a bare mkdir leaves them unrecognized — TESTED; a Repos-managed Git folder is the documented fallback). On genie_code operate via the workspace path / executeCode, mindful of the FUSE create-then-validate gap (clone, then confirm with os.path.exists(<artifact_root>/.git) before writing). This clone/check is the only filesystem side effect of resolve_root.
4. Echo, do not persist. Return client_context + artifact_root + skills_install_root + skill_ref_root for the caller to use immediately and to echo the project-root + skill-load rules to the operator. No state file is written — bootstrap step 0 remains the sole writer of section 0, so there is no "abort if path exists" conflict and no half-initialized state file.

Outputs: { client_context, artifact_root, skills_install_root, skill_ref_root } (ephemeral). The calling prompt resolves its relative artifact path as <ARTIFACT_ROOT>/<relpath>, loads any repo-relative skill path X/Y/SKILL.md as <skill_ref_root>/X/Y/SKILL.md via readSkillFile (§8), and echoes: "artifacts resolve under the workshop project root (artifact_root, the git-cloned user project on Genie Code — not the skills copy) and skills load under skill_ref_root (= skills/<clone-folder> = skills/ + basename of skills_install_root on Genie Code), never the page CWD."

Errors: None that halt — resolve_root is fail-soft. If detection is ambiguous, default to ide_cli / repo-root and note the assumption; the later bootstrap step 0 is authoritative.

Operation: resolve_spec

When: Called automatically as the final step of bootstrap. May also be re-invoked manually if the PRD changes mid-workshop (rare; prefer restarting from bootstrap).

Inputs:

Behavior:

1. Read the PRD contents from prd_path and compute prd_sha256.
2. Load the schema from references/spec-schema.md and the prompt from references/resolver-prompt.md.
3. Derive variant_id deterministically from Workshop Choices (pathway, track) per the resolver prompt's Variant-ID Derivation Table. Inject it into the user prompt.
4. Call llm_endpoint with the system + user prompts. Expect a single YAML document with exactly six top-level keys: variant_id, resources, ui, agent, governance, spec_provenance.
5. Run the deterministic guards listed in the resolver prompt's "Post-resolution Guards" section:
   • YAML parses cleanly into a dict with the expected top-level keys.
   • Every validation rule in references/spec-schema.md §"Validation Rules" passes.
   • Consumer cross-check: each agent.tools[].name of kind: function with language: python reconciles with the PRD Tools Table.
   • Placeholder guard: no resource-ID-shaped strings leaked through.
   • Variant-ID echo check: emitted variant_id equals the one passed in.
   • MCP ref resolution: every agent.tools[].mcp_server_ref (kind=mcp) maps to an agent.mcp_servers[].name.
6. If any guard fails, retry once with the validation errors appended to the user prompt. Second failure halts bootstrap.
7. Split the validated YAML by top-level key and write each block into its matching state-file section (## Variant, ## Resources, ## UI, ## Agent, ## Governance, ## Spec Provenance), replacing the <pending> placeholder body with a fenced ```yaml block containing the resolved content.
8. Stamp ## Spec Provenance with resolved_at, resolver_version: "2.0", schema_version: "2.0", prd_sha256, and llm_endpoint.

Outputs: No return value; mutates the live state file.

Errors: Validation failure (after one retry), missing PRD file, unreachable llm_endpoint, or any LLM response that is not parseable YAML with the six expected keys — all halt bootstrap.

Downstream contract: Every consuming skill declares which fields it reads via a machine-parseable fields_read: YAML list in its frontmatter (see § Field Consumer Contract below and references/spec-schema.md §"Field Consumer Contract"). Prompts in Instructions.md and WALKTHROUGH.md reference resolved content by dotted path (e.g. ui.user_journeys, agent.tools, governance.scorer_suite.guidelines) instead of inlining domain-specific content. This is what makes the workshops use-case-agnostic.

Operation: hydrate_from_files

When: Called once per workshop, before any prompt that reads state://AgentSpec, state://AppSpec, or state://DataSpec. The Agents Accelerator visible path calls it from prompt uc_resources_foundation (input_id 200, order 40), right after op enter succeeds and before any UC schema/volume creation.

Purpose: The Agents Accelerator design pair (docs/agent_spec.yaml from prompt 38, docs/agent_tool_plan.yaml from prompt 39) becomes the source of truth for the agent's intent. hydrate_from_files lifts those file values into the live state file so every downstream consumer (Track A build prompts, MLflow SDLC suite at prompts 50-56) keeps reading from state://AgentSpec, state://AppSpec, and state://Spec Provenance without an additional visible-path step. This is additive to resolve_spec: PRD-only LLM-driven workflows that never produce the docs/*.yaml files continue to work unchanged.

Inputs:

Behavior:

1. Read agent_spec_yaml. Copy scalar/list agent.* fields directly into the state file's ## Agent section as a fenced yaml block: model, capabilities, personas, system_prompt, benchmark_seeds, must_do, must_not_do. File values override any prior resolve_spec LLM output silently; the file is the source of truth.

   Tool projection rule (preserves the v2.0 fields_read: agent.tools contract without rewriting any consumer). The Agent Spec produced by step 38 follows the 00b schema (tool_recommendations, NOT agent.tools). Hydration MUST project tools into state://AgentSpec.agent.tools[] using these three sub-rules:

   a. Seed state://AgentSpec.agent.tools[] from docs/agent_spec.yaml.tool_recommendations.managed_databricks[] plus tool_recommendations.external[]. Map each entry to the v2.0 tool discriminated-union shape: populate kind (hosted | function | mcp), name, surface, io_contract, readonly, plus the kind-specific fields (hosted_type + resource_ref, or language, or mcp_server_ref). Carry selected_by_default forward to pre-mark entries. b. Overlay docs/agent_tool_plan.yaml.selected_tools[] on top. Any Tool Plan entry with the same name REPLACES the spec recommendation — binding selection wins over loose recommendation. Tool Plan entries with no matching spec recommendation are appended. c. Tool families absent from BOTH the spec and the Tool Plan are NOT written into agent.tools[]. Skipped families are recorded as skipped, not failed (consistent with step 44 semantics).

   The projection is the only legitimate way state://AgentSpec.agent.tools[] becomes populated on the Agents Accelerator visible path. Step 38 does NOT and MUST NOT write agent.tools[] directly into docs/agent_spec.yaml; downstream prompts that still cite agent.tools[] (e.g. step 44's prerequisite block before Pass 3.5) MUST be updated to read tool_recommendations (loose) plus selected_tools (binding) instead.

2. Read agent_tool_plan_yaml. Merge selected_tools[], selected_mcp_servers[], runtime_config.llm, and resource_grants into ## Agent under new keys selected_tools, selected_mcp_servers, runtime_config, and resource_grants. Tools selected by the user in the Tool Plan win over the Agent Spec's recommendations.

3. Read ui_design_md. Parse loose markdown headings into ## UI (pages[], personas[], user_journeys[]) on a best-effort basis. If the document is structured differently or only contains free-form prose, write the verbatim markdown into ## UI.raw_markdown and emit a non-fatal warning so downstream SDLC prompts can still find personas/journeys textually.

4. Stamp ## Spec Provenance. Compute prd_sha256 from prd_path and write resolved_at (current UTC ISO timestamp), resolver_version: "3.0" (new tag distinguishing file-based hydration from LLM resolve_spec's "2.0"), schema_version: "2.0", prd_sha256, and hydrated_from_files: true.

5. Optional ## Resources (DataSpec). If the PRD declares a Lakehouse/Resources section (Bronze tables, Genie Spaces, Vector Search indexes, etc.) and ## Resources is already populated by an earlier resolve_spec run, leave it untouched. Otherwise write ## Resources as optional: true with tables: [], mark_skipped: "no Lakehouse track", signalling downstream prompts that state://DataSpec.* lookups should fall back gracefully (e.g. KA branch C in prompt 42 reads from docs/design_prd.md + docs/agent_spec.yaml.agent.capabilities instead of state://DataSpec.glossary).

6. Idempotency. Re-running with the same inputs is a no-op: each section is regenerated from the file values, sha256 is stable, and the state file ends in the same byte sequence (modulo the resolved_at timestamp, which is allowed to drift). Re-running with newer docs/*.yaml files overwrites cleanly.

Outputs: { hydrated: true, sections_written: ["## Agent", "## UI", "## Resources", "## Spec Provenance"] }. The Agents Accelerator step 40 records hydrated_from_files: true and resolver_version: "3.0" in its op exit captured map.

Errors:

• Missing required input file → halt with an explicit pointer to the producing prompt: agent_spec_yaml → 38, agent_tool_plan_yaml → 39, ui_design_md → 04, prd_path → 03, state_path → bootstrap.
• agent_spec.yaml missing agent.model → halt with a pointer to prompt 38's model selection rule (Pass 1 / Pass 2 of the Agents Accelerator cleanup).
• agent_tool_plan.yaml.runtime_config.llm.endpoint equals the literal YAML-path string docs/agent_spec.yaml.agent.model → halt with the Pass 2 placeholder rule citation. This is defense-in-depth; prompt 39's generated prompt already forbids this.
• Any value at a documented Agent Spec / Tool Plan path is still wrapped in {...} (e.g. {agent_sql_catalog}) → halt with the Pass 2 placeholder-handling rule. The user must rerun prompt 39 with real values.

Downstream contract: After hydrate_from_files runs, every prompt that consumes state://AgentSpec.agent.*, state://AppSpec.ui.*, or state://Spec Provenance.* sees the file-derived values. state://DataSpec.* is <pending> or optional: true unless the Lakehouse track produced one. SDLC prompts (50-56) MUST handle the optional/pending DataSpec case gracefully — they already do (the Agents Accelerator visible path no longer requires Lakehouse outputs), but the optional: true flag makes the contract explicit.

LLM driver prompt: See references/hydrator-prompt.md for the actual prompt that an LLM-driven implementation runs to execute this operation. That file is to hydrate_from_files what references/resolver-prompt.md is to resolve_spec.

Operation: enter

When: At the top of every workshop prompt, before any domain skill or command runs.

Inputs:

Behavior:

1. Locate the live state file:

   • First, resolve state_file_root from the ## Environment Capabilities block (section 0). Every path below is relative to it — the local repo root for client_context: ide_cli, the git-folder workspace path for genie_code. On a pre-capability state file (no section 0), default state_file_root to the repo root and proceed without assuming a deploy channel.
   • If $APP_NAME is known (Pathways A/B/C), use <app_root>/.vibecoding-state.md (= <state_file_root>/<app_name>/.vibecoding-state.md, the TOP-LEVEL app dir — NOT apps_lakebase/<app_name>/).
   • Else if $AGENT_APP_NAME is known (Track A agent app, Pathways C/D), use <agent_app_root>/.vibecoding-state.md (= <state_file_root>/<agent_app_name>/.vibecoding-state.md, the TOP-LEVEL agent app dir — NOT apps_lakebase/<agent_app_name>/).
   • Else if dp_bundle_root is resolved (a data-product / lakehouse run with no app or agent app — e.g. the Gold-design→Bronze→Silver→Gold→semantic pipeline), use <dp_bundle_root>/.vibecoding-state.md (= <state_file_root>/{user_schema_prefix}_<use_case_slug>_dab/.vibecoding-state.md). This is the canonical DP-track live file — the data-product analog of <app_root> / <agent_app_root>. The FIRST data-product prompt to run (Gold design, step 09 — or Bronze, step 10, if design was skipped) bootstrap-creates it from references/state-template.md if absent (a real create, copying the template + filling Workshop Choices from the prior example/ bootstrap file if present — not just resolve_root); every later DP step appends to it. Do NOT leave data-product state in the temporary example/ bootstrap path — that path carries no durable record and was the root cause of "state survived only in chat summary."
   • Else fall back to the bootstrap path <state_file_root>/example/<use_case_slug>/.vibecoding-state.md (pre-bootstrap only — once dp_bundle_root/app_root/agent_app_root is known, migrate/bootstrap-create the canonical file above).
   • If none of these exists yet: for the dp_bundle_root/app_root/agent_app_root canonical paths, bootstrap-create the file from the template (this is the first prompt of that track); only stop and tell the operator to run bootstrap first if even use_case_slug/Workshop Choices are unknown.

2. Schema v2.0 gate (hard fail). Parse the ## Spec Provenance YAML block. If schema_version != "2.0", halt with:

   State file uses schema v<X> — this repo is strictly v2.0.
   Run: python scripts/migrate-spec-v1-to-v2.py <path-to-state-file>
   Then re-run this prompt.
   

   No best-effort reads against older shapes.

3. Read end-to-end. Treat Workshop Choices, Global Variables, and Captured Resource IDs as authoritative. Never ask the operator for a value that already exists in state.

4. Multi-file resolution via state_file_set. Parse the ## State File Set block.

   • If state_file_set.secondary.path is <pending> or null, treat the located file as the only source — done.
   • If secondary is declared and prompt_id is in secondary.required_for_prompts, read the secondary file too. Halt if it does not exist (remediation: run bootstrap for the missing side or correct secondary.path).
   • Walk both files following lookup_order (e.g. ["primary", "secondary"]). For each canonical field requested by the prompt, the first hit wins.
   • For any canonical field present in both files with different values: halt unless conflict_policy: primary_wins is set explicitly. With primary_wins, use the primary value and append the conflict to ## State Contract Audit (fields_read_but_never_produced / captured_fields_with_no_consumer are unaffected; conflicts get their own audit row).

5. Apply canonical_names aliasing on read. Parse the ## Canonical Names block. Whenever the prompt reads an env var, HTTP header, jq path, or state field listed as a legacy/incorrect spelling on the left of a canonical_names map, resolve to the canonical name on the right. If the map's value is null (e.g. http_headers.x-forwarded-user-info: null), the name does not exist; halt and surface a hint pointing at the canonical alternatives. state_contract_audit performs the same checks at audit time.

6. Enforce the prior gate if require_prior_gate is set. On mismatch, halt unless a matching entry exists in state_overrides[] (see step 7). Mismatches that are NOT covered by an override stop the workshop.

7. Apply state_overrides[] (fail-closed escape hatch). Parse ## State Overrides. An override entry covers a failing gate when ALL of the following hold: prompt_id matches the current prompt; gate_type matches the failing gate (require_prior_gate for step 6, hard_assert / preflight_check for step 9 below, pathway_applicability for step 8); and expires_at is in the future relative to the current ISO timestamp. A covered failure is treated as satisfied and the override is logged in the prompt's Resolved issues / workarounds Per-Step Log entry. Expired or missing entries DO NOT cover the failure — enter halts. Cross-session continuity (e.g. resuming from a previous run's state file) is recorded as a state_override whose reason cites the earlier run's evidence; it is NOT a prose exception.

8. Consult the Pathway Applicability Matrix (below). If the prompt does not apply for this pathway/track and no state_override with gate_type: pathway_applicability covers it, synthesize a ## Prompt <prompt_id> — Skipped (N/A for pathway <X>) section with Gate: Skipped — N/A for pathway <X>, append it, and return a skipped: true signal so the prompt body short-circuits. With a covering override, proceed (the override reason is logged in the prompt's Per-Step Log entry).

9. Enforce deferred_actions[]. Parse ## Deferred Actions. Halt if the current prompt's role is in any open deferred_action's target_prompt_roles[] and its divergence_check evaluates to false (or fails to parse under the divergence-check grammar in references/spec-schema.md § Deferred Actions). Halt is suppressed only when a state_override with gate_type: hard_assert (or preflight_check) on the current prompt_id exists AND its references[] contains "deferred_action:<id>" matching the action's id. If divergence_check returns true, flip status to resolved and proceed. Entries with status: waived are skipped without evaluation.

10. Enforce mlflow_eval_known_quality_issues[]. Parse ## MLflow Eval Known Quality Issues. If the current prompt's role appears in any open issue's target_prompt_roles_blocked[], halt with a remediation hint citing id, source_prompt_role, and error_signature — unless a state_override exists on the current prompt_id whose references[] contains "known_issue:<id>" matching the issue's id. The issue's error_signature SHOULD be a name from gate_load_bearing_checks[] so audits and verify summaries align, but enter halts purely on target_prompt_roles_blocked[] membership and status: open — it does NOT consult gate_load_bearing_checks[] directly (that list drives state_contract_audit and the verify-job warning_policy: block_if_load_bearing rule per § Gate Load Bearing Checks in references/spec-schema.md).

11. Enforce preflight_check_registry. Parse ## Preflight Check Registry. For each registry entry, if the current prompt's role appears in blocks_prompt_roles[], evaluate the matching state field per the State-field mapping table in references/spec-schema.md § Preflight Check Registry. If the pass condition is not met (the field is <pending>, missing, or fails the predicate), halt with a remediation hint pointing at owner. The halt is suppressed only when a matching state_override with gate_type: preflight_check exists on the current prompt_id whose affected_state_field matches the check's state field. For reflection_lm_large_context_probe, the check is treated as passing only when a synchronous ≥80000-character probe has been run against the currently bound llm_role_endpoints.reflection_lm.endpoint and endpoint_guardrail_audit[<reflection_lm.endpoint>].long_context_ok == true AND accepted_min_context_chars >= 80000 — the generic bootstrap endpoint guardrail pass is NOT sufficient on its own. The owning skill (instruction_iteration) MUST invoke the probe synchronously before any 08b diff-summary helper or iteration helper call. For genie_code_manifest_loaded (G3, the one client-conditional check), evaluate it only when environment_capabilities.client_context == 'genie_code' — it is inert on ide_cli — and on Genie Code halt the deploy roles until environment_capabilities.genie_code_manifest_loaded == true (the agent has read skills/genie-code-environment in-thread); see references/spec-schema.md § Genie Code manifest-load gate.

12. Resolve variables. Return the subset of state the prompt body needs (it is declared in the prompt's enter invocation — e.g. APP_NAME, PROFILE, warehouse_id). Always also return the environment-capability set so any deploy/run instruction the prompt emits uses the resolved verb + channel instead of assuming a local IDE: bundle_deploy.verb (always `bund

…(truncated)