Expose the build model as data: fallout describe --json and plan --json

[ChrisonSimtian]

Problem

To learn what a Fallout build can do, a tool has to read Build.cs, follow its partial classes, resolve the attributes, and re-run the dependency resolution in its head. --help renders that same information as human text, and there is no machine-readable form of it. There is also no way to ask what a target would run without running it.

Outcome

Two read-only commands that print the build model as JSON and never execute a target.

• fallout describe --json — every target, the dependency edges (DependsOn, Before, After, Triggers), every parameter with its CLR type, default value and required flag, tool requirements, and descriptions.
• fallout plan <target> --json — the ordered list of targets that would run, with skip reasons. This is the existing plan resolution with the executor not attached.

Acceptance criteria

• fallout describe --json emits a schema-versioned document covering targets, dependency edges, parameters, and tool requirements
• fallout plan <target> --json emits the resolved plan and invokes no target
• Both commands leave the working tree untouched and run no external tool
• Both exit non-zero with a machine-readable error when the build project fails to load
• --help is rendered from the same model, so the human and machine views cannot drift

Notes

src/Fallout.Build/Execution/ExecutionPlanner.cs already computes the plan, then discards it into the console. #391 (the Serilog and NDJSON output work) names describe --json as a motivation but does not track it.

[ChrisonSimtian]

Part of #648 (the AI-native build interface epic), milestone AI-native build interface.

[phmatray]

Picking this up. Below is a design trail for it — brainstorm, spec, and a task-by-task implementation plan grounded in the current tree.

Two findings worth flagging before the detail:

1. BuildGraphUtility already is most of describe. It projects targets and all four relation kinds into a schema-versioned document and is snapshot-tested. This issue is mostly filling in parameters[] and toolRequirements[] and giving it a stdout path — not building a model from scratch. It also means landing this delivers Emit declared build parameters into build-graph.json #499 from the same projection, with SchemaVersion still at 1.

2. "Runs no external tool" rules out an IOnBuildInitialized extension. BuildManager.Execute calls ToolRequirementService.EnsureToolRequirements before the IOnBuildInitialized hooks, and that writes nuget.csproj / package.json and shells out to dotnet restore. So --help and --plan already pay for a restore before they print anything. The emission has to short-circuit above that line.

One deviation from the issue text: the commands land as the build-side parameters --describe and --plan --json. CommandDispatcher routes bare arguments to the build and reserves :-prefixed tokens for CLI commands, so a bare describe would collide with a target of that name.

Note for whoever has triage rights: the plan below is written to live in the issue description, where its checkboxes feed the task-list progress meter and agent tooling can read them. I don't have write access to move it there — happy for it to be lifted into the body.

---

Related: #648 (epic), #499, #644, #643, #391, #646, #381

Spelling resolved during design: fallout describe --json / fallout plan <target> --json land as the build-side parameters --describe and --plan --json. CommandDispatcher routes bare arguments to the build and reserves :-prefixed tokens for CLI commands, so a bare describe would collide with a target of that name. See the Spec's Surface and Scope / non-goals.

🧠 Brainstorm

Problem / context

Every consumer that wants to know what a build can do re-derives it. The VS Code extension, the
planned MCP server (#646), and any AI agent all need targets, dependency edges, parameters and tool
requirements as data. Today:

• HandleHelpRequestsAttribute (src/Fallout.Build/Execution/Extensions/HandleHelpRequestsAttribute.cs)
  renders that information as padded text straight from Build.ExecutableTargets and
  ValueInjectionUtility.GetParameterMembers. Text only, no model.
• BuildGraphUtility (src/Fallout.Build/Execution/Extensions/BuildGraphUtility.cs) already has
  a schema-versioned projection of targets and all four relation kinds — but it carries no
  parameters and no tool requirements, and SerializeBuildGraphAttribute writes it to
  TemporaryDirectory/build-graph.json as a side effect rather than to stdout.
• --plan exists but opens an HTML graph in a browser (HandlePlanRequestsAttribute). There is no
  way to ask what a target would run and get the answer back on a pipe.

The model exists in three partial, drifting forms. This issue collapses them into one.

Prior art in the tree (this is a fill-in, not a greenfield)

Piece	Where	State
Target + edge projection	BuildGraphUtility.GetModel	Exists, snapshot-tested, SchemaVersion = 1
Plan resolution	ExecutionPlanner.GetExecutionPlan	Exists, already called in BuildManager.Execute
Plan handed to extensions	IOnBuildInitialized(executableTargets, executionPlan)	Exists
Parameter enumeration	ValueInjectionUtility.GetParameterMembers	Exists (--help uses it)
[Required] / [Secret] / value providers	src/Fallout.Build/ParameterAttribute.cs	Exist
Tool requirements	ExecutableTarget.ToolRequirements + class-level [Requires]	Exist

The constraint that decides the design

BuildManager.Execute runs in this order:

GetExecutionPlan  ->  ToolRequirementService.EnsureToolRequirements  ->  IOnBuildInitialized hooks

EnsureToolRequirements writes nuget.csproj / package.json into the temporary directory and
shells out to dotnet restore (and apt-get). Both existing read-only handlers — --help and
--plan — are IOnBuildInitialized extensions, so they already pay for a restore before they
print anything. The acceptance criterion "runs no external tool" therefore cannot be met by another
IOnBuildInitialized extension. The emission has to happen earlier than any existing hook.

Approaches

A. New IOnBuildPlanned public extension hook, fired between planning and tool requirements.
Architecturally the tidiest, and the natural home for #644's plan-time effect gating too. Rejected for
now: IBuildExtension and its siblings are public API, and FT-7 (#312) is chartered to formalize
the extension pipeline with typed phases. Minting a public hook here would pre-commit that design and
then have to live with it forever under rule #2. Revisit as a follow-up once #312 lands.

B. Internal introspection short-circuit in BuildManager.Execute, on a shared model. <- recommended
An internal BuildIntrospectionService called immediately after GetExecutionPlan and before
EnsureToolRequirements. It owns the two read-only requests, writes JSON to stdout and returns an
exit code; BuildManager returns it and never reaches the executor. No new public extension surface,
no ordering change for anyone else, and the "no external tool" guarantee is structural rather than a
promise. --help is then re-pointed at the same model so the two views cannot drift.

C. Just print the existing build-graph.json. Cheapest, and wrong: the file is written after
tool requirements, carries neither parameters nor tool requirements nor the plan, and makes a
side-effect file the contract instead of stdout.

Recommendation

B. Additive, blast radius stays inside Fallout.Build, and it fixes the ordering problem by
construction rather than by convention. The shared model is BuildGraphUtility's existing
BuildGraphModel, extended additively — which means landing this also delivers #499's
parameters[] in build-graph.json for free, from the same projection, with SchemaVersion still
at 1.

📋 Spec

Goal

Two read-only requests that print the build model as JSON on stdout, execute no target, run no
external tool, and touch no file in the working tree.

Surface

Invocation	Output	Exit
fallout --describe	describe document on stdout	0
fallout <targets> --plan --json	plan document on stdout	0
fallout <targets> --plan	unchanged — HTML graph opened in a browser	0
either, when the build throws before emission	error envelope on stdout	non-zero

--describe is machine-facing by definition and always emits JSON; a redundant --json alongside it
is accepted and ignored. --json is a format modifier that today only changes --plan. Both requests
suppress the logo and the end-of-run outcome tables.

Flow

flowchart TD
    A["BuildManager.Execute"] --> B["ExecutableTargetFactory.CreateAll"]
    B --> C["ExecutionPlanner.GetExecutionPlan"]
    C --> D{"--describe or --plan --json?"}
    D -- yes --> E["BuildIntrospectionService writes JSON to stdout"]
    E --> F["return 0 - executor never reached"]
    D -- no --> G["ToolRequirementService.EnsureToolRequirements<br/>writes files, runs dotnet restore"]
    G --> H["IOnBuildInitialized - help, plan HTML, build-graph.json"]
    H --> I["BuildExecutor.Execute"]

Loading

The short-circuit sits above EnsureToolRequirements, which is the whole point: everything below
that line has side effects.

Describe document

Additive extension of the existing BuildGraphUtility.BuildGraphModel. SchemaVersion stays 1 —
new fields only, so the VS Code extension's SUPPORTED_SCHEMA_VERSION gate keeps passing.

{
  "version": 1,
  "falloutVersion": "2026.1.0-preview.42",
  "targets": [
    {
      "name": "Compile", "description": "Builds all projects", "declaredIn": "Build",
      "default": false, "listed": true,
      "dependsOn": ["Restore"], "after": [], "triggeredBy": [], "triggers": ["Publish"],
      "toolRequirements": [{ "kind": "nuget", "packageId": "GitVersion.Tool", "version": "5.12.0" }]
    }
  ],
  "parameters": [
    {
      "name": "NuGetApiKey", "type": "System.String", "declaredIn": "IPublish",
      "description": "API key for nuget.org.",
      "required": true, "secret": true, "list": true, "default": null,
      "allowedValues": null
    }
  ]
}

• targets[] keeps its current shape field-for-field; toolRequirements is new and additive.
• kind is one of path / nuget / npm / aptget, from the ToolRequirement subclass.
• parameters[] is projected from ValueInjectionUtility.GetParameterMembers(build.GetType(), includeUnlisted: false) — the exact set --help lists, inherited component parameters included.
• type is the CLR type name after GetNullableType() unwrapping, so int? reports System.Int32.
• required reflects [Required]; secret reflects [Secret]. Secret values are never emitted — default is null for any secret: true parameter regardless of what is injected.
• allowedValues comes from ParameterAttribute.ValueProviderType / ValueProviderMember when both are set, otherwise null.
• Ordering is ordinal by name throughout, matching the existing determinism guarantee.

Plan document

{
  "version": 1,
  "invokedTargets": ["Test"],
  "plan": [
    { "name": "Restore", "order": 0, "invoked": false, "skip": null,
      "staticConditions": [], "dynamicConditions": [] },
    { "name": "Test", "order": 2, "invoked": true, "skip": "via parameter",
      "staticConditions": ["IsServerBuild"], "dynamicConditions": [] }
  ]
}

skip carries "via parameter" for targets named in --skip, matching BuildExecutor's own reason
string. Conditions are emitted as their declared text, never evaluated: StaticConditions and
DynamicConditions hold user delegates, and running them would violate "invokes no target". A
consumer learns what gates a target, not the gate's current value.

Error envelope

When an exception escapes before emission, BuildManager's existing catch block writes this instead
of the human message and returns the existing ErrorExitCode:

{ "version": 1, "error": { "kind": "TargetExecutionException", "message": "..." } }

Known caveat, deliberately out of scope

A versionless tool requirement (NuGetPackageRequirement constructed with version: null) resolves
the latest version over the network in its constructor, during ExecutableTargetFactory.CreateAll
— before any short-circuit can intervene. That lookup predates this issue and affects --help today
just as much. "Runs no external tool" is therefore scoped to this code path; narrowing the
constructor's eager resolution is separate work.

Scope / non-goals

• In: the two documents, the shared projection, --help re-pointed at it, build-graph.json inheriting parameters[] and toolRequirements[].
• Out: a fallout :describe CLI command. A thin :describe forwarder can land later, once the build-side contract is stable.
• Out: routing Serilog to stderr. Both requests force NoLogo and suppress the outcome tables, and at default verbosity nothing else reaches stdout before the document. Full stdout/stderr separation is Spectre sink: Logging & output architecture — Serilog event core + Spectre.Console frame + NDJSON machine path #391's job.
• Out: evaluating conditions, bumping SchemaVersion, and any change to --plan's existing HTML behaviour.

Assumptions

1. --describe and --json are new built-in parameters, so both must be added to the built-in allowlist at src/Fallout.Build/Execution/ValueInjectionUtility.cs:63 — members declared on FalloutBuild are otherwise skipped by value injection.
2. BuildIntrospectionService takes FalloutBuild, not IFalloutBuild, so the public build interface gains no members.
3. --describe earns its own parameter rather than --help --json, because --help's contract is "human text"; overloading it would make the machine view a mode of the human one instead of the other way round.
4. A consumer build that already declares a parameter named Json will shadow the new modifier. Accepted: the same is already true of Plan, Help and Continue.

🛠️ Implementation plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Emit the build model and the resolved execution plan as JSON on stdout, from one shared projection that --help also renders.

Architecture: Extend BuildGraphUtility's existing BuildGraphModel additively with parameters[] and per-target toolRequirements[], then short-circuit BuildManager.Execute between GetExecutionPlan and EnsureToolRequirements with an internal BuildIntrospectionService. No new public extension hook; SchemaVersion stays 1.

Tech Stack: .NET 10, System.Text.Json, xUnit + FluentAssertions + Verify.Xunit.

Spec: the 📋 Spec section above.

Global Constraints

• .NET SDK pinned by global.json (10.0.100, rollForward: latestMinor).
• Central package versions only — add to Directory.Packages.props, never a Version= on a PackageReference. This plan adds no package.
• Tests: xUnit + FluentAssertions + Verify.Xunit only. src/Fallout.Build → tests/Fallout.Build.Specs, mirrored namespaces.
• No conventional-commit prefixes (AGENTS.md rule Add CodeQL workflow for security scanning #7). Commit subjects are functional descriptions — no feat: / fix: / chore:.
• No per-file license headers.
• Additive only. BuildGraphUtility.SchemaVersion stays 1; if a change would force a bump, stop and re-scope — the VS Code extension gates on it.
• BuildIntrospectionService is internal. Fallout.Build.Specs already has internals access via the root AssemblyInfo.cs.
• Never @-mention the former NUKE maintainer, and never add him as a commit co-author.
• Branch off main; PR gets target/vCurrent plus a changelog-category label from .github/release.yml.

Single-suite test command used throughout:

dotnet test tests/Fallout.Build.Specs/Fallout.Build.Specs.csproj --filter "FullyQualifiedName~<ClassName>"

---

Task 1: Project tool requirements onto the target model

Files:

• Modify: src/Fallout.Build/Execution/Extensions/BuildGraphUtility.cs
• Test: tests/Fallout.Build.Specs/BuildGraphUtilitySpecs.cs
• Snapshots: tests/Fallout.Build.Specs/BuildGraphUtilitySpecs.*.verified.json

Interfaces:

• Produces: BuildGraphUtility.ToolRequirementModel(string Kind, string PackageId, string Version); TargetModel gains a trailing IReadOnlyList<ToolRequirementModel> ToolRequirements.

• Consumes: Fallout.Common.Tooling.ToolRequirement and its subclasses PathToolRequirement, NuGetPackageRequirement, NpmPackageRequirement, AptGetPackageRequirement (src/Fallout.Tooling/ToolRequirement.cs).

• Step 1: Write the failing test. Add to BuildGraphUtilitySpecs.cs, and give SampleGraph()'s compile target two requirements so the snapshot exercises both a versioned and a version-free kind:

compile.ToolRequirements.Add(new NuGetPackageRequirement("GitVersion.Tool", "5.12.0"));
compile.ToolRequirements.Add(new PathToolRequirement("git"));

[Fact]
public void Tool_requirements_are_projected_with_their_kind()
{
    var compile = BuildGraphUtility.GetModel(SampleGraph(), SampleVersion)
        .Targets.Single(x => x.Name == "Compile");

    compile.ToolRequirements.Should().BeEquivalentTo(new[]
    {
        new BuildGraphUtility.ToolRequirementModel("nuget", "GitVersion.Tool", "5.12.0"),
        new BuildGraphUtility.ToolRequirementModel("path", "git", null),
    }, x => x.WithStrictOrdering());
}

• Step 2: Run it and confirm it fails. dotnet test tests/Fallout.Build.Specs/Fallout.Build.Specs.csproj --filter "FullyQualifiedName~BuildGraphUtilitySpecs" → FAIL: ToolRequirementModel does not exist.
• Step 3: Implement the projection in BuildGraphUtility.cs — add the record, add the property to TargetModel as the last positional member, and extend ToModel:

internal sealed record ToolRequirementModel(string Kind, string PackageId, string Version);

// Ordinal-sorted by kind then id, for the same determinism reason as SortedNames.
private static IReadOnlyList<ToolRequirementModel> ToolRequirements(ExecutableTarget target)
    => target.ToolRequirements.Select(ToModel)
        .OrderBy(x => x.Kind, StringComparer.Ordinal)
        .ThenBy(x => x.PackageId, StringComparer.Ordinal)
        .ToList();

private static ToolRequirementModel ToModel(ToolRequirement requirement)
    => requirement switch
    {
        NuGetPackageRequirement x => new("nuget", x.PackageId, x.Version),
        NpmPackageRequirement x => new("npm", x.PackageId, x.Version),
        AptGetPackageRequirement x => new("aptget", x.PackageId, null),
        PathToolRequirement x => new("path", x.PathExecutable, null),
        _ => new("unknown", requirement.GetType().Name, null),
    };

• Step 4: Run the suite → the new test passes and the two .verified.json snapshots now fail on the added field. Review both diffs: toolRequirements must be the only change, and version must still read 1.
• Step 5: Accept the snapshots (rename .received.json over .verified.json) and re-run the suite → PASS.
• Step 6: Commit git commit -m "Project tool requirements onto the build-graph target model"

---

Task 2: Project declared parameters onto the model

Files:

• Modify: src/Fallout.Build/Execution/Extensions/BuildGraphUtility.cs
• Test: tests/Fallout.Build.Specs/BuildGraphUtilitySpecs.cs

Interfaces:

• Produces: BuildGraphUtility.ParameterModel(string Name, string Type, string DeclaredIn, string Description, bool Required, bool Secret, bool List, string Default, IReadOnlyList<string> AllowedValues); BuildGraphModel gains a trailing IReadOnlyList<ParameterModel> Parameters; a new overload GetModel(targets, falloutVersion, IReadOnlyCollection<MemberInfo> parameterMembers).

• Consumes: ValueInjectionUtility.GetParameterMembers, ParameterService.GetParameterDashedName, ParameterService.GetParameterDescription, and ParameterAttribute / RequiredAttribute / SecretAttribute from src/Fallout.Build/ParameterAttribute.cs.

• The existing two-argument GetModel stays and forwards with an empty member list, so SerializeBuildGraphAttribute keeps compiling untouched.

• Step 1: Add a sample build type to BuildGraphUtilitySpecs.cs exercising every flag, next to the existing SampleBuild:

private sealed class SampleParameterBuild : FalloutBuild
{
    [Parameter("API key for nuget.org.")] [Required] [Secret]
    public string NuGetApiKey { get; }

    [Parameter("Configuration to build.", List = false)]
    public int? Retries { get; }
}

• Step 2: Write the failing test.

[Fact]
public void Parameters_are_projected_without_leaking_secret_values()
{
    var members = ValueInjectionUtility.GetParameterMembers(
        typeof(SampleParameterBuild), includeUnlisted: false);

    var parameters = BuildGraphUtility
        .GetModel(SampleGraph(), SampleVersion, members).Parameters;

    var apiKey = parameters.Single(x => x.Name == "NuGetApiKey");
    apiKey.Required.Should().BeTrue();
    apiKey.Secret.Should().BeTrue();
    apiKey.Default.Should().BeNull();
    apiKey.Type.Should().Be("System.String");
    apiKey.DeclaredIn.Should().Be(nameof(SampleParameterBuild));

    // Nullable value types report their underlying CLR type.
    parameters.Single(x => x.Name == "Retries").Type.Should().Be("System.Int32");
}

• Step 3: Run it and confirm it fails. --filter "FullyQualifiedName~BuildGraphUtilitySpecs" → FAIL: no three-argument GetModel.
• Step 4: Implement the projection in BuildGraphUtility.cs:

private static ParameterModel ToModel(MemberInfo member)
{
    var attribute = member.GetCustomAttribute<ParameterAttribute>();
    var secret = member.GetCustomAttribute<SecretAttribute>() != null;
    return new ParameterModel(
        ParameterService.GetParameterDashedName(member),
        member.GetMemberType().GetNullableType().FullName,
        member.DeclaringType?.Name,
        ParameterService.GetParameterDescription(member),
        Required: member.GetCustomAttribute<RequiredAttribute>() != null,
        Secret: secret,
        List: attribute?.List ?? true,
        // Never emit a secret's value, whatever is injected.
        Default: null,
        AllowedValues: null);
}

• Step 5: Run the suite → PASS, and accept the snapshot updates for the added parameters: [] field on the two existing graph snapshots.
• Step 6: Wire the richer model into the emitted file. In src/Fallout.Build/Execution/Extensions/SerializeBuildGraphAttribute.cs, pass ValueInjectionUtility.GetParameterMembers(Build.GetType(), includeUnlisted: false) to GetJsonString, so build-graph.json carries parameters[] too. This closes Emit declared build parameters into build-graph.json #499.
• Step 7: Run the full suite dotnet test tests/Fallout.Build.Specs/Fallout.Build.Specs.csproj → PASS, and confirm Schema_version_is_1 still passes.
• Step 8: Commit git commit -m "Project declared parameters onto the build-graph model"

---

Task 3: --describe emits the model before tool requirements run

Files:

• Create: src/Fallout.Build/Execution/BuildIntrospectionService.cs
• Modify: src/Fallout.Build/FalloutBuild.cs (next to the existing Plan / Help parameters, around line 128)
• Modify: src/Fallout.Build/Execution/ValueInjectionUtility.cs:63 (built-in allowlist)
• Modify: src/Fallout.Build/Execution/BuildManager.cs
• Test: tests/Fallout.Build.Specs/BuildIntrospectionServiceSpecs.cs

Interfaces:

• Produces: internal static class BuildIntrospectionService with bool IsRequested(FalloutBuild build) and string GetDocument(FalloutBuild build, IReadOnlyCollection<ExecutableTarget> targets, IReadOnlyCollection<ExecutableTarget> plan).

• Produces: FalloutBuild.Describe and FalloutBuild.Json, both [Parameter] public bool { get; }.

• Consumes: BuildGraphUtility.GetJsonString(targets, falloutVersion, parameterMembers) from Task 2.

• Step 1: Write the failing test in a new tests/Fallout.Build.Specs/BuildIntrospectionServiceSpecs.cs:

[Fact]
public void Describe_document_is_parseable_json_carrying_targets_and_parameters()
{
    var build = new SampleParameterBuild { /* Describe is set via the test seam below */ };
    var json = BuildIntrospectionService.GetDocument(build, SampleGraph(), plan: Array.Empty<ExecutableTarget>());

    var document = JsonDocument.Parse(json).RootElement;
    document.GetProperty("version").GetInt32().Should().Be(1);
    document.GetProperty("targets").GetArrayLength().Should().Be(4);
    document.GetProperty("parameters").GetArrayLength().Should().BeGreaterThan(0);
}

• Step 2: Run it and confirm it fails. --filter "FullyQualifiedName~BuildIntrospectionServiceSpecs" → FAIL: type not found.
• Step 3: Add the two parameters to src/Fallout.Build/FalloutBuild.cs:

/// <summary>
/// Gets a value whether to print the build model as JSON and exit without executing anything.
/// </summary>
[Parameter("Prints the build model as JSON and exits without executing any target.")]
public bool Describe { get; }

/// <summary>
/// Gets a value whether read-only requests emit machine-readable JSON on stdout.
/// </summary>
[Parameter("Emits machine-readable JSON on stdout for read-only requests (--plan).")]
public bool Json { get; }

• Step 4: Add both to the built-in allowlist in src/Fallout.Build/Execution/ValueInjectionUtility.cs:63 — append nameof(FalloutBuild.Describe) and nameof(FalloutBuild.Json) to the array alongside Plan, Help, Continue, NoLogo, Verbosity, Partition. Without this, value injection skips them and the flags read false forever.
• Step 5: Create BuildIntrospectionService:

internal static class BuildIntrospectionService
{
    internal static bool IsRequested(FalloutBuild build) => build.Describe || (build.Plan && build.Json);

    internal static string GetDocument(
        FalloutBuild build,
        IReadOnlyCollection<ExecutableTarget> targets,
        IReadOnlyCollection<ExecutableTarget> plan)
        => build.Describe
            ? BuildGraphUtility.GetJsonString(
                targets,
                FindFalloutVersion(),
                ValueInjectionUtility.GetParameterMembers(build.GetType(), includeUnlisted: false))
            : GetPlanJson(build, plan);   // Task 4 fills this in
}

• Step 6: Run the suite → PASS.
• Step 7: Short-circuit BuildManager.Execute. Immediately after build.ExecutionPlan = ExecutionPlanner.GetExecutionPlan(...) and before ToolRequirementService.EnsureToolRequirements(...):

// Read-only introspection short-circuits above EnsureToolRequirements on purpose: everything
// below this line writes files or shells out, which --describe / --plan --json must not do.
if (BuildIntrospectionService.IsRequested(build))
{
    Console.Out.Write(BuildIntrospectionService.GetDocument(build, build.ExecutableTargets, build.ExecutionPlan));
    return build.ExitCode ??= 0;
}

• Step 8: Keep stdout clean — two more edits in the same file. Gate the logo: if (!build.NoLogo && !BuildIntrospectionService.IsRequested(build)). Then gate the local Finish() so the outcome tables never print over the document: change its guard to if (build.ExecutionPlan == null || BuildIntrospectionService.IsRequested(build)) return;.
• Step 9: Verify end-to-end against the repo's own build. Run ./build.ps1 --describe > describe.json, confirm describe.json parses (Get-Content describe.json | ConvertFrom-Json), confirm git status --porcelain is empty, and confirm the run printed no logo and no outcome table. Delete describe.json.
• Step 10: Commit git commit -m "Add --describe emitting the build model as JSON before tool requirements run"

---

Task 4: --plan --json emits the resolved execution plan

Files:

• Modify: src/Fallout.Build/Execution/BuildIntrospectionService.cs
• Test: tests/Fallout.Build.Specs/BuildIntrospectionServiceSpecs.cs

Interfaces:

• Produces: BuildIntrospectionService.PlanModel(int Version, IReadOnlyList<string> InvokedTargets, IReadOnlyList<PlanEntryModel> Plan) and PlanEntryModel(string Name, int Order, bool Invoked, string Skip, IReadOnlyList<string> StaticConditions, IReadOnlyList<string> DynamicConditions).

• Consumes: ExecutableTarget.Invoked, .StaticConditions, .DynamicConditions (both List<(string Text, Func<bool> Delegate)>), and the --skip values from ParameterService.GetParameter<string[]>(() => build.SkippedTargets).

• Step 1: Write the failing test.

[Fact]
public void Plan_document_preserves_order_and_never_evaluates_conditions()
{
    var evaluated = false;
    var restore = new ExecutableTarget { Name = "Restore" };
    var compile = new ExecutableTarget { Name = "Compile", Invoked = true };
    compile.StaticConditions.Add(("IsServerBuild", () => { evaluated = true; return true; }));

    var json = BuildIntrospectionService.GetPlanJson(
        invokedTargets: new[] { "Compile" }, plan: new[] { restore, compile }, skippedTargets: null);

    var entries = JsonDocument.Parse(json).RootElement.GetProperty("plan");
    entries[0].GetProperty("name").GetString().Should().Be("Restore");
    entries[0].GetProperty("order").GetInt32().Should().Be(0);
    entries[1].GetProperty("invoked").GetBoolean().Should().BeTrue();
    entries[1].GetProperty("staticConditions")[0].GetString().Should().Be("IsServerBuild");
    evaluated.Should().BeFalse("the plan reports what gates a target, never the gate's value");
}

• Step 2: Run it and confirm it fails. --filter "FullyQualifiedName~BuildIntrospectionServiceSpecs" → FAIL: GetPlanJson not found.
• Step 3: Implement GetPlanJson — plan order is the list's own order (it is already topologically sorted), so use the index, and take only the Text of each condition tuple:

internal static string GetPlanJson(
    IReadOnlyCollection<string> invokedTargets,
    IReadOnlyCollection<ExecutableTarget> plan,
    IReadOnlyCollection<string> skippedTargets)
{
    var skipped = (skippedTargets ?? Array.Empty<string>())
        .Select(x => x.Replace("-", string.Empty)).ToList();

    var entries = plan.Select((target, index) => new PlanEntryModel(
        target.Name,
        index,
        target.Invoked,
        // Matches BuildExecutor's own reason string; an empty --skip skips everything.
        skippedTargets != null && (skipped.Count == 0 || skipped.Contains(target.Name, StringComparer.OrdinalIgnoreCase))
            ? "via parameter"
            : null,
        target.StaticConditions.Select(x => x.Text).ToList(),
        target.DynamicConditions.Select(x => x.Text).ToList())).ToList();

    return new PlanModel(BuildGraphUtility.SchemaVersion, invokedTargets.ToList(), entries)
        .ToJson(serializerOptions);
}

• Step 4: Run the suite → PASS.
• Step 5: Route it from GetDocument — replace the Task 3 placeholder call with GetPlanJson(ParameterService.GetParameter<string[]>(() => build.InvokedTargets) ?? Array.Empty<string>(), plan, ParameterService.GetParameter<string[]>(() => build.SkippedTargets)).
• Step 6: Verify end-to-end. ./build.ps1 Test --plan --json prints the plan and exits 0 without opening a browser; ./build.ps1 Test --plan still opens the HTML graph. Confirm git status --porcelain is empty after the JSON run.
• Step 7: Commit git commit -m "Add --plan --json emitting the resolved execution plan"

---

Task 5: Machine-readable error envelope on failure

Files:

• Modify: src/Fallout.Build/Execution/BuildIntrospectionService.cs
• Modify: src/Fallout.Build/Execution/BuildManager.cs (the catch (Exception exception) block)
• Test: tests/Fallout.Build.Specs/BuildIntrospectionServiceSpecs.cs

Interfaces:

• Produces: BuildIntrospectionService.GetErrorJson(Exception exception) returning {"version":1,"error":{"kind":"...","message":"..."}}.

• Step 1: Write the failing test.

[Fact]
public void Error_envelope_names_the_exception_kind_and_message()
{
    var json = BuildIntrospectionService.GetErrorJson(new InvalidOperationException("boom"));

    var error = JsonDocument.Parse(json).RootElement.GetProperty("error");
    error.GetProperty("kind").GetString().Should().Be(nameof(InvalidOperationException));
    error.GetProperty("message").GetString().Should().Be("boom");
}

• Step 2: Run it and confirm it fails. → FAIL: GetErrorJson not found.
• Step 3: Implement GetErrorJson using the same serializerOptions, with kind = exception.GetType().Name.
• Step 4: Run the suite → PASS.
• Step 5: Wire it into the catch block in BuildManager.Execute — inside catch, after exception = exception.Unwrap();, emit the envelope instead of the human message when introspecting, keeping the existing ErrorExitCode:

if (BuildIntrospectionService.IsRequested(build))
{
    Console.Out.Write(BuildIntrospectionService.GetErrorJson(exception));
    return build.ExitCode ??= ErrorExitCode;
}

• Step 6: Verify end-to-end. Temporarily throw from a target's factory, run ./build.ps1 --describe, confirm stdout parses as the envelope and $LASTEXITCODE is non-zero, then revert the temporary throw.
• Step 7: Commit git commit -m "Emit a machine-readable error envelope for introspection failures"

---

Task 6: Render --help from the shared model

Files:

• Modify: src/Fallout.Build/Execution/Extensions/HandleHelpRequestsAttribute.cs
• Test: tests/Fallout.Build.Specs/HandleHelpRequestsSpecs.cs (create)

Interfaces:

• Consumes: BuildGraphUtility.GetModel(targets, falloutVersion, parameterMembers) from Task 2.

• GetTargetsText() and GetParametersText() keep their current signatures and observable output; only their input changes from raw reflection to the model.

• Step 1: Write the characterization test first so the refactor is provably output-preserving:

[Fact]
public void Help_lists_every_target_the_model_marks_listed()
{
    var model = BuildGraphUtility.GetModel(SampleGraph(), SampleVersion);
    var text = new HandleHelpRequestsAttribute { Build = new SampleParameterBuild() }.GetTargetsText();

    foreach (var target in model.Targets.Where(x => x.Listed))
        text.Should().Contain(target.Name);

    // Publish is unlisted in the sample graph and must not appear.
    text.Should().NotContain("Publish");
}

• Step 2: Run it and confirm the starting state. --filter "FullyQualifiedName~HandleHelpRequestsSpecs" → it should FAIL only because the spec file/type wiring is new; fix the wiring until it passes against the current implementation. That green run is the baseline the refactor must preserve.
• Step 3: Refactor GetTargetsText to iterate BuildGraphUtility.GetModel(Build.ExecutableTargets, falloutVersion: null).Targets.Where(x => x.Listed), reading DependsOn for the -> dependency list instead of target.ExecutionDependencies.
• Step 4: Refactor GetParametersText to iterate the model's Parameters, using ParameterModel.Name, .Description and .DeclaredIn. Keep the existing split between custom parameters (DeclaredIn != nameof(FalloutBuild)) and inherited ones, and keep the existing padding and line-wrapping behaviour byte-for-byte.
• Step 5: Run the suite → PASS, unchanged from the Step 2 baseline.
• Step 6: Compare the human output by eye. Run ./build.ps1 --help and diff it against the same command on main; it must be identical.
• Step 7: Run the whole test suite ./build.ps1 Test → PASS.
• Step 8: Commit git commit -m "Render --help from the shared build model so the human and machine views cannot drift"

[ChrisonSimtian]

@phmatray please lets make sure that Step 5: Create BuildIntrospectionService is NOT implemented as a static class unless there is a good reason. Static classes are a code smell and can and should be avoided.