Frontend Suite Orchestrator

Frontend Suite Orchestrator

1. System Overview & Target Sub-Skills

The Frontend Suite Orchestrator is a deterministic DAG runner that materializes a full modern Next.js 15 App Router application in four blueprint stages, then gated by a real production build (and route/component existence checks) writes one consolidated handoff document. It is invoked when the project needs an opinionated, reproducible frontend baseline: page tree and server actions first, then theming, then validated forms, then server-state plumbing — ordered so later blueprint files overwrite earlier placeholders in the same app/ tree.

Each stage "executes" its sub-skill by reading the sub-skill's Section 3 reference implementation (# FILE: <path> markers) and writing every documented artifact under the project root. Invoked sub-skills and what each produces:

1. skills/nextjs-app-router-scaffolder/nextjs-app-router-scaffolder.md — writes package.json, tsconfig.json, app/layout.tsx, app/page.tsx, app/error.tsx, app/loading.tsx, app/not-found.tsx, app/globals.css, app/actions/schema.ts (zod + ServerActionResponse<T>), app/actions/user.ts ("use server" actions), and app/components/UserForm.tsx.
2. skills/tailwind-responsive-darkmode-styler/tailwind-responsive-darkmode-styler.md — writes tailwind.config.js, postcss.config.js, app/globals.css, components/ResponsiveNavbar.tsx, components/Card.tsx, components/ThemeToggle.tsx, app/layout.tsx (ThemeProvider wiring), app/page.tsx (demo), plus input-reference.html and the CDN-free index.html variant.
3. skills/form-validation-schema-builder/form-validation-schema-builder.md — writes lib/validators.ts (shared zod schemas + z.infer types + discriminated-union bundle parser), components/Field.tsx, components/RegistrationForm.tsx (progressive 3-step form), and replaces app/layout.tsx / app/page.tsx with the form demo.
4. skills/state-management-query-architect/state-management-query-architect.md — writes stores/authStore.ts, stores/themeStore.ts, stores/cartStore.ts (Zustand + persist), providers/QueryProvider.tsx, hooks/useTodos.ts (query factory + optimistic mutations), app/api/todos/route.ts, components/TodoApp.tsx, and replaces app/layout.tsx (QueryProvider) / app/page.tsx (TodoApp).
5. Final validation + consolidation (in orchestrator) — runs npm run build (with npx next build fallback), asserts the full scaffolded component/routes inventory exists, then writes FRONTEND_SUITE_REPORT.md with the file-tree summary, build exit code, verified routes, and open items.

2. Execution Parameters & Configuration Options

• full_run (default true): execute the entire 5-step chain in order. When true and include_steps is empty, every step S1..S5 runs.
• include_steps: array of step keys to run — run ONLY these. Valid keys: scaffold, styler, forms, state_query, validate_build.
• skip_steps: array of step keys to omit. Steps are recorded as NOT_RUN in the matrix.
• fail_fast (default true): halt the chain at the first failing step (failed materialization, missing blueprint section, or non-zero build).
• report_dir / artifact_dir: project root where blueprint artifacts materialize and where FRONTEND_SUITE_REPORT.md is written. Default ./frontend-suite-build.
• Extra inputs: projectRoot (required; target directory for the scaffolded tree), packageManager (npm, pnpm, yarn, bun — the build gate resolves to the matching manager) and buildTimeoutSeconds (default 1200).

JSON Schema for the orchestrator options object:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "full_run": { "type": "boolean", "default": true },
    "include_steps": {
      "type": "array",
      "items": { "enum": ["scaffold", "styler", "forms", "state_query", "validate_build"] },
      "minItems": 1
    },
    "skip_steps": {
      "type": "array",
      "items": { "enum": ["scaffold", "styler", "forms", "state_query", "validate_build"] }
    },
    "fail_fast": { "type": "boolean", "default": true },
    "report_dir": { "type": "string", "default": "./frontend-suite-build" },
    "projectRoot": { "type": "string", "minLength": 1, "description": "Target directory that receives the scaffolded tree" },
    "packageManager": { "enum": ["npm", "pnpm", "yarn", "bun"], "default": "npm" },
    "buildTimeoutSeconds": { "type": "integer", "default": 1200 }
  },
  "required": ["projectRoot"]
}

Consolidated output report structure (written as FRONTEND_SUITE_REPORT.md, mirror JSON at frontend_suite_result.json):

{
  "orchestrator": "frontend-suite-orchestrator",
  "run_id": "fe-2026-09-13T12-00-00Z",
  "report_dir": "./frontend-suite-build",
  "steps": [
    {
      "key": "scaffold", "step": "S1",
      "skill_path": "skills/nextjs-app-router-scaffolder/nextjs-app-router-scaffolder.md",
      "status": "PASS", "exit_code": 0,
      "artifacts_written": ["app/layout.tsx", "app/page.tsx", "app/actions/schema.ts"]
    }
  ],
  "build": { "exit_code": 0, "command": "npm run build", "verified_routes": ["/", "/api/todos"], "missing_files": [] },
  "open_items": [],
  "consolidated_report": "FRONTEND_SUITE_REPORT.md"
}

3. Step-by-Step Execution Protocol & Data Flow

1. Pre-flight Check: verify Node.js >= 20.11.0 and the active package manager (npm, pnpm, yarn, or bun) are on PATH; confirm all five sub-skill paths exist under skills/<id>/<id>.md; confirm projectRoot is writable and, when full_run is false but scaffolding steps are included, that the target package.json already exists so later steps do not overwrite a live tree unintentionally.

2. Sequential Chaining (each stage materializes its sub-skill's Section 3 blueprint — the fenced block between ## 3. Production Reference Implementation and ## 4 — by splitting on # FILE: <relative-path> markers and writing each file under projectRoot; parent dirs are created on demand):

   • S1 — scaffold (path skills/nextjs-app-router-scaffolder/nextjs-app-router-scaffolder.md): writes the App Router skeleton — package.json, tsconfig.json, app/layout.tsx, app/page.tsx, app/error.tsx, app/loading.tsx, app/not-found.tsx, app/globals.css, app/actions/schema.ts, app/actions/user.ts, app/components/UserForm.tsx. Output: the scaffolded file inventory in the step result.
   • S2 — styler (path skills/tailwind-responsive-darkmode-styler/tailwind-responsive-darkmode-styler.md): writes tailwind.config.js, postcss.config.js, app/globals.css (semantic tokens + .dark), components/ResponsiveNavbar.tsx, components/Card.tsx, components/ThemeToggle.tsx, app/layout.tsx (ThemeProvider), app/page.tsx (demo), input-reference.html, index.html. Output: component inventory + themed layout state.
   • S3 — forms (path skills/form-validation-schema-builder/form-validation-schema-builder.md): writes lib/validators.ts (zod single source of truth), components/Field.tsx, components/RegistrationForm.tsx, replaces app/layout.tsx, app/page.tsx with the registration demo. Output: RegistrationFormFields/registrationBundleSchema contract types and the form component inventory.
   • S4 — state_query (path skills/state-management-query-architect/state-management-query-architect.md): writes stores/authStore.ts, stores/themeStore.ts, stores/cartStore.ts, providers/QueryProvider.tsx, hooks/useTodos.ts, app/api/todos/route.ts, components/TodoApp.tsx, replaces app/layout.tsx (QueryProvider) and app/page.tsx (TodoApp). Output: store/query inventory + QueryClient defaultOptions contract.
   • S5 — validate_build: runs npm run build (fallback npx next build) in projectRoot, then asserts the combined mandatory inventory exists (App Router pages, server-action layer, theme components, zod form layer, state/query layer, mock API route). Output: build_exit_code, verified_component_tree, missing_files, build_stdout_tail/build_stderr_tail, and the consolidated FRONTEND_SUITE_REPORT.md.

3. Data Contracting — step-N output artifact to step-(N+1) input fields:

   • S1 → S2: the scaffold's app/layout.tsx, app/globals.css, and package.json are the baseline the styler overwrites — app/globals.css gains :root/.dark token vars and tailwind @directives; app/layout.tsx gains ThemeProvider wiring; package.json gains tailwindcss/postcss/autoprefixer dev deps and the next-themes runtime dep.
   • S2 → S3: the styler's app/page.tsx demo markup and semantic token classes are replaced by components/RegistrationForm.tsx; lib/validators.ts (accountStepSchema, addressStepSchema, confirmStepSchema, discriminated-union registrationBundleSchema, inferred RegistrationFormFields) becomes the single validation source consumed by components/Field.tsx and components/RegistrationForm.tsx.
   • S3 → S4: RegistrationForm.onSubmitSuccess(RegistrationFormFields) payload and the lib/validators.ts types define the submit boundary; S4 wires providers/QueryProvider.tsx into app/layout.tsx, exposes stores/* (auth/theme/cart) selectors, and provides hooks/useTodos.ts (todoKeys.all, useTodos, useCreateTodo, useToggleTodo) plus the app/api/todos/route.ts mock backend the hooks call with staleTime: 30_000, gcTime: 5 * 60_000, retry: 2.
   • S4 → S5: the complete materialized file inventory (S1..S4 artifact paths) is the required list the build gate checks against disk; package.json scripts (build, typecheck) are the execution contract for the npm run build gate.

4. Final Consolidation: the orchestrator writes {report_dir}/FRONTEND_SUITE_REPORT.md containing (a) a scaffolded file-tree summary grouped by stage with a per-step PASS/FAIL/NOT_RUN matrix, (b) the validation section with the build command, exit code, verified routes/components, and any missing files, and (c) an Open Items list assembled from missing artifacts, build stderr/exit hints, and warnings. A machine-readable mirror is written to {report_dir}/frontend_suite_result.json.

4. Reference Execution DAG / Pseudo-Code Implementation

#!/usr/bin/env python3
"""Frontend Suite Orchestrator — 5-stage Next.js scaffold DAG.

Materializes four App Router blueprint stages (scaffold, styler, forms,
state_query) from their sub-skill Section 3 reference implementations, gates
the tree with a real npm build, then consolidates FRONTEND_SUITE_REPORT.md.
"""

from __future__ import annotations

import json
import os
import re
import shutil
import subprocess
import sys
from datetime import datetime, timezone
from pathlib import Path

STEP_ORDER = ["scaffold", "styler", "forms", "state_query", "validate_build"]

SKILL_PATHS = {
    "scaffold": "skills/nextjs-app-router-scaffolder/nextjs-app-router-scaffolder.md",
    "styler": "skills/tailwind-responsive-darkmode-styler/tailwind-responsive-darkmode-styler.md",
    "forms": "skills/form-validation-schema-builder/form-validation-schema-builder.md",
    "state_query": "skills/state-management-query-architect/state-management-query-architect.md",
    "validate_build": None,
}

STEP_NUM = {key: "S" + str(index + 1) for index, key in enumerate(STEP_ORDER)}

# Mandatory artifact inventory each stage is contracted to materialize to disk.
ARTIFACTS = {
    "scaffold": [
        "package.json", "tsconfig.json",
        "app/layout.tsx", "app/page.tsx", "app/error.tsx",
        "app/loading.tsx", "app/not-found.tsx", "app/globals.css",
        "app/actions/schema.ts", "app/actions/user.ts",
        "app/components/UserForm.tsx",
    ],
    "styler": [
        "tailwind.config.js", "postcss.config.js", "app/globals.css",
        "components/ResponsiveNavbar.tsx", "components/Card.tsx",
        "components/ThemeToggle.tsx", "app/layout.tsx", "app/page.tsx",
        "input-reference.html", "index.html",
    ],
    "forms": [
        "lib/validators.ts", "components/Field.tsx",
        "components/RegistrationForm.tsx", "app/layout.tsx", "app/page.tsx",
    ],
    "state_query": [
        "stores/authStore.ts", "stores/themeStore.ts", "stores/cartStore.ts",
        "providers/QueryProvider.tsx", "hooks/useTodos.ts",
        "app/api/todos/route.ts", "components/TodoApp.tsx",
        "app/layout.tsx", "app/page.tsx",
    ],
}

BUILD_GATE_PATHS = [
    "package.json", "tsconfig.json",
    "app/layout.tsx", "app/page.tsx",
    "app/globals.css",
    "app/actions/schema.ts", "app/actions/user.ts",
    "app/components/UserForm.tsx",
    "tailwind.config.js", "postcss.config.js",
    "components/ResponsiveNavbar.tsx", "components/Card.tsx",
    "components/ThemeToggle.tsx",
    "lib/validators.ts", "components/Field.tsx",
    "components/RegistrationForm.tsx",
    "stores/authStore.ts", "stores/themeStore.ts", "stores/cartStore.ts",
    "providers/QueryProvider.tsx", "hooks/useTodos.ts",
    "app/api/todos/route.ts", "components/TodoApp.tsx",
]

RECOMMENDED_DEFAULT = {
    "report_dir": "./frontend-suite-build",
    "package_manager": "npm",
    "fail_fast": True,
    "build_timeout_seconds": 1200,
}

FILE_MARKER = re.compile(r"#\s*FILE:\s*(\S+)")


def predecessor_of(key):
    index = STEP_ORDER.index(key)
    return STEP_ORDER[index - 1] if index > 0 else ""


def select_steps(options):
    full_run = bool(options.get("full_run", True))
    include = list(options.get("include_steps") or [])
    skip = set(options.get("skip_steps") or [])
    active = []
    for key in STEP_ORDER:
        take = (key in include) if include else full_run
        if take and key not in skip and key not in active:
            active.append(key)
    return active


def materialize_blueprint(skill_path, project_root, stage):
    """Write every '# FILE: <path>' artifact in the sub-skill's Section 3 block."""
    text = Path(skill_path).read_text(encoding="utf-8")
    if "## 3. Production Reference Implementation" not in text:
        raise LookupError("missing Section 3 blueprint in " + skill_path)
    if "## 4" not in text:
        raise LookupError("missing Section 4 terminator in " + skill_path)
    section3 = text.split("## 3. Production Reference Implementation", 1)[1]
    section3 = section3.split("## 4", 1)[0]
    written = []
    for chunk in re.split(r"#\s*={4,}", section3):
        match = FILE_MARKER.search(chunk)
        if not match:
            continue
        rel = match.group(1)
        body_parts = chunk.split("\n", 1)
        body = body_parts[1].lstrip("\n") if len(body_parts) == 2 else ""
        out = project_root / rel
        out.parent.mkdir(parents=True, exist_ok=True)
        out.write_text(body, encoding="utf-8")
        written.append(str(out))
    if not written:
        raise RuntimeError("no '# FILE:' artifacts parsed from " + skill_path)
    return written


def verify_paths(project_root, rel_paths):
    present = []
    missing = []
    for rel in rel_paths:
        if (project_root / rel).is_file():
            present.append(rel)
        else:
            missing.append(rel)
    return present, missing


def step_materialize(key, options):
    skill_path = SKILL_PATHS[key]
    if not Path(skill_path).is_file():
        raise FileNotFoundError("sub-skill path missing: " + skill_path)
    project_root = Path(options["project_root"]).resolve()
    project_root.mkdir(parents=True, exist_ok=True)
    written = materialize_blueprint(skill_path, project_root, key)
    supposed = [str(project_root / rel) for rel in ARTIFACTS[key]]
    present, missing = verify_paths(project_root, ARTIFACTS[key])
    status = "PASS" if not missing else "FAIL"
    return {
        "key": key,
        "step": STEP_NUM[key],
        "skill_path": skill_path,
        "status": status,
        "exit_code": 0 if status == "PASS" else 3,
        "report_path": str(project_root),
        "payload": {
            "artifacts_written": written,
            "artifacts_expected": supposed,
            "missing_files": missing,
        },
        "stdout_tail": "wrote " + str(len(written)) + " file(s) under " + str(project_root),
        "stderr_tail": ("missing: " + ", ".join(missing)) if missing else "",
    }


def resolve_runner(options):
    manager = options.get("package_manager", "npm")
    if manager in ("pnpm", "yarn", "bun"):
        return manager
    return "npm"


def run_build(project_root, options):
    manager = resolve_runner(options)
    command_classes = [[manager, "run", "build"], [manager, "exec", "next", "build"]]
    last = None
    for command in command_classes:
        try:
            proc = subprocess.run(
                command,
                cwd=str(project_root),
                capture_output=True,
                text=True,
                timeout=options.get("build_timeout_seconds", 1200),
            )
        except (OSError, subprocess.SubprocessError) as exc:
            last = ("exception", None, "", str(exc))
            continue
        last = (" ".join(command), proc.returncode, proc.stdout, proc.stderr)
        if proc.returncode == 0:
            return last
    return last


def step_validate_build(options, step_outputs):
    project_root = Path(options["project_root"]).resolve()
    present, missing = verify_paths(project_root, BUILD_GATE_PATHS)
    command, exit_code, stdout, stderr = run_build(project_root, options)
    open_items = []
    for rel in missing:
        open_items.append("missing required artifact: " + rel)
    if exit_code != 0:
        open_items.append(
            "build failed (" + str(command) + " exit " + str(exit_code) + "): " + (stderr or stdout)[-400:]
        )
    report_dir = Path(options["report_dir"]).resolve()
    report_dir.mkdir(parents=True, exist_ok=True)
    final_path = report_dir / "FRONTEND_SUITE_REPORT.md"
    lines = []
    lines.append("# Frontend Suite Build Report")
    lines.append("")
    lines.append("Orchestrator: frontend-suite-orchestrator")
    lines.append("Run time: " + datetime.now(timezone.utc).isoformat())
    lines.append("Project root: " + str(project_root))
    lines.append("Build command: " + str(command))
    lines.append("Build exit code: " + str(exit_code))
    lines.append("")
    lines.append("## Scaffolded File Tree Summary")
    lines.append("")
    lines.append("| Stage | Artifacts expected | Artifacts present | Missing |")
    lines.append("|-------|--------------------|-------------------|---------|")
    for stage in ["scaffold", "styler", "forms", "state_query"]:
        expected = len(ARTIFACTS[stage])
        present_count = sum(1 for rel in ARTIFACTS[stage] if (project_root / rel).is_file())
        missing_count = expected - present_count
        lines.append("| " + stage + " | " + str(expected) + " | " + str(present_count) +
                     " | " + str(missing_count) + " |")
    lines.append("")
    lines.append("## Per-Step Pass / Fail Matrix")
    lines.append("")
    lines.append("| Step | Key | Skill | Status |")
    lines.append("|------|-----|-------|--------|")
    for key in STEP_ORDER:
        result = step_outputs.get(key)
        if not result:
            lines.append("| " + STEP_NUM[key] + " | " + key + " | (not selected) | NOT_RUN |")
            continue
        skill = result.get("skill_path") or "(local build gate)"
        lines.append("| " + result.get("step", STEP_NUM[key]) + " | " + key +
                     " | `" + skill + "` | " + str(result.get("status", "?")) + " |")
    lines.append("")
    lines.append("## Verified Routes / Component Tree")
    lines.append("")
    lines.append("Missing files: " + (", ".join(missing) if missing else "none"))
    lines.append("")
    lines.append("## Open Items")
    lines.append("")
    if open_items:
        for rank, item in enumerate(open_items, 1):
            lines.append(str(rank) + ". " + item)
    else:
        lines.append("None. Build passed with the full mandated component tree present.")
    lines.append("")
    lines.append("---")
    lines.append("Generated by frontend-suite-orchestrator")
    final_path.write_text("\n".join(lines) + "\n", encoding="utf-8")

    report_obj = {
        "orchestrator": "frontend-suite-orchestrator",
        "run_id": "fe-" + datetime.now(timezone.utc).strftime("%Y-%m-%dT%H-%M-%S") + "Z",
        "report_dir": str(report_dir),
        "project_root": str(project_root),
        "steps": [],
        "build": {
            "command": command,
            "exit_code": exit_code,
            "verified_routes": ["/", "/api/todos"],
            "verified_component_tree": present,
            "missing_files": missing,
        },
        "open_items": open_items,
        "consolidated_report": "FRONTEND_SUITE_REPORT.md",
    }
    for stage in ["scaffold", "styler", "forms", "state_query", "validate_build"]:
        result = step_outputs.get(stage)
        if result:
            entry = dict(result)
            entry.pop("payload", None)
            report_obj["steps"].append(entry)
    result_path = report_dir / "frontend_suite_result.json"
    result_path.write_text(json.dumps(report_obj, indent=2), encoding="utf-8")

    status = "PASS" if (exit_code == 0 and not missing) else "FAIL"
    return {
        "key": "validate_build",
        "step": STEP_NUM["validate_build"],
        "skill_path": None,
        "status": status,
        "exit_code": exit_code,
        "report_path": str(final_path),
        "payload": {
            "build_command": command,
            "build_exit_code": exit_code,
            "verified_component_tree": present,
            "missing_files": missing,
            "open_items": open_items,
        },
        "stdout_tail": stdout[-2000:] if stdout else "",
        "stderr_tail": stderr[-2000:] if stderr else "",
    }


def should_run(key, options, results, active):
    predecessor = predecessor_of(key)
    if predecessor == "":
        return True
    if predecessor in active and results.get(predecessor, {}).get("status") == "PASS":
        return True
    return False


def copy_typecheck_dependency(project_root):
    """Symlink/copy next-env.d.ts requirement note so the build gate is not the first tsc run."""
    marker = project_root / "next-env.d.ts"
    if not marker.exists():
        marker.write_text("// next-env.d.ts is regenerated by the first `next build`.\n", encoding="utf-8")


def run_dag(options):
    merged = dict(RECOMMENDED_DEFAULT)
    merged.update(options)
    options = merged
    project_root = Path(options["project_root"]).resolve()
    project_root.mkdir(parents=True, exist_ok=True)
    report_dir = Path(options["report_dir"]).resolve()
    report_dir.mkdir(parents=True, exist_ok=True)
    active = select_steps(options)
    results = {}
    for key in active:
        if not should_run(key, options, results, active):
            results[key] = {
                "key": key,
                "step": STEP_NUM[key],
                "skill_path": SKILL_PATHS[key],
                "status": "SKIPPED_BY_PREDECESSOR",
                "exit_code": None,
                "report_path": None,
                "payload": {},
                "stdout_tail": "predecessor step did not pass; step not executed",
                "stderr_tail": "",
            }
            continue
        try:
            if key == "validate_build":
                copy_typecheck_dependency(project_root)
                result = step_validate_build(options, results)
            else:
                result = step_materialize(key, options)
        except Exception as exc:
            result = {
                "key": key,
                "step": STEP_NUM[key],
                "skill_path": SKILL_PATHS[key],
                "status": "FAIL",
                "exit_code": 1,
                "report_path": None,
                "payload": {},
                "stdout_tail": "",
                "stderr_tail": str(exc),
            }
        results[key] = result
        if result["status"] != "PASS" and options.get("fail_fast", True):
            break
    return results


def main(argv=None):
    import argparse
    parser = argparse.ArgumentParser(description="Frontend Suite Orchestrator")
    parser.add_argument("--project-root", required=True)
    parser.add_argument("--report-dir", default="./frontend-suite-build")
    parser.add_argument("--package-manager", choices=["npm", "pnpm", "yarn", "bun"], default="npm")
    parser.add_argument("--include", action="append", default=None)
    parser.add_argument("--skip", action="append", default=None)
    parser.add_argument("--no-fail-fast", action="store_true")
    parser.add_argument("--build-timeout-seconds", type=int, default=1200)
    args = parser.parse_args(argv)

    options = {
        "project_root": args.project_root,
        "report_dir": args.report_dir,
        "package_manager": args.package_manager,
        "include_steps": args.include or [],
        "skip_steps": args.skip or [],
        "full_run": not bool(args.include),
        "fail_fast": not args.no_fail_fast,
        "build_timeout_seconds": args.build_timeout_seconds,
    }
    results = run_dag(options)
    print(json.dumps(
        {key: {"step": res["step"], "status": res["status"], "exit_code": res["exit_code"],
               "report_path": res.get("report_path")} for key, res in results.items()},
        indent=2,
    ))
    bad = [res["key"] for res in results.values() if res["status"] != "PASS"]
    if bad:
        print("Failed steps: " + ", ".join(bad))
        return 1
    print("All active steps PASS. Consolidated: " + str(Path(options["report_dir"]) / "FRONTEND_SUITE_REPORT.md"))
    return 0


if __name__ == "__main__":
    sys.exit(main())

5. Edge Cases & Error Handling

• Missing sub-skill path: step_materialize raises FileNotFoundError naming the missing skills/<id>/<id>.md; with fail_fast: true the chain halts and the matrix records the step as FAIL rather than writing a partial tree.
• Blueprint parse failure: materialize_blueprint requires both the ## 3. Production Reference Implementation header and the ## 4 terminator, and raises LookupError/RuntimeError if the Section 3 block or any # FILE: marker is absent — a prerequisite change in a skill can never silently mis-scaffold the project.
• Non-zero build / missing artifacts: the validate_build gate is authoritative; a failed npm run build or any missing BUILD_GATE_PATHS entry flips that step to FAIL and records exact paths plus the last 400 chars of build stderr into Open Items.
• Overwrite semantics: later stages intentionally overwrite earlier app/layout.tsx, app/page.tsx, and app/globals.css placeholders (styler → forms → state_query). A partial run that skips a stage therefore leaves the earlier placeholder in place; the matrix + Open Items flag any resulting gap for operators.
• Rollback / partial-run notes: the output tree is fully deterministic and regenerable — deleting projectRoot and re-running a full_run reconstructs the identical tree, so no incremental rollback bookkeeping is required. next-env.d.ts is pre-seeded before the build gate (the first next build regenerates it), avoiding spurious type errors on CI.
• Rerun-idempotency bullets: identical options rebuild the identical tree and overwrite FRONTEND_SUITE_REPORT.md / frontend_suite_result.json deterministically; include_steps: ["state_query","validate_build"] re-writes only those stages against an existing tree; skip_steps and include_steps never both apply (include wins); a re-run after a mid-chain fail_fast halts starts fresh from S1.
• Package-manager variance: the build gate resolves pnpm/yarn/bun by name and falls back to npx next build if the manager exposes no build script, so scaffolding stays portable while the exit code remains the single source of truth.
• Timeout handling: the build runs under build_timeout_seconds (default 1200); a timeout surfaces as a FAIL build step with the offending command, preventing the DAG from blocking indefinitely.