Spec runner silently ignores unknown top-level directives (e.g. `features:`); should warn or error

[shivamstaq]

Summary

The gotit spec runner silently accepts unknown top-level directives in YAML specs without any warning or error. This led to an incident where four spec files in a downstream project (graph-harness) used features: [p1-multi-language] thinking it was the wave-gate directive, when the runner only honors requires: [feature:p1-multi-language]. The specs ran on every CI invocation regardless of the wave flag, and a teammate reported them as phase1 failures because they were inside the phase1/ tree but not actually gated.

Reproduction

# yaml-language-server: $schema=https://github.com/shivamstaq/gotit/raw/main/schema/spec.schema.json
spec_version: 1
name: gating-mismatch
features: [some-feature]    # ← silently ignored
requires:
  - feature:other-feature   # ← only this is honored
steps:
  - name: noop
    command: "true"
    assert: [{ type: exit_code, expected: 0 }]

Even with GRAPH_HARNESS_E2E_FEATURES (the env var the runner reads) unset, the spec runs because the runner ignores the misspelled features: directive and only checks requires:. The author has no signal that their gate is non-functional.

Recovery example

The fix in the downstream project: shivamstaq/graph-harness@f5afe42 — converted four specs from features: [p1-multi-language] to requires: [feature:p1-multi-language]. After the fix, the specs SKIP cleanly when the env var is unset and PASS when it is set. But finding the silent-acceptance was only obvious once the wrong-syntax form was compared side-by-side with a correctly-gated spec.

Suggested fix

Either:

1. Strict-mode rejection (preferred): unknown top-level keys in spec YAML are a parse error with a useful message — unknown directive "features" at line N; did you mean "requires"?. This catches typos at parse time, not at "I expected this to skip and it didn't."

2. Warning mode: print gotit: warning: spec X has unknown directive "features" (ignored) to stderr at load time. Less disruptive than an error but still surfaces the issue.

Either would have prevented the incident. Strict-mode rejection is the cleaner contract since spec YAMLs are version-pinned via spec_version.

Context

The yaml-language-server: $schema=... annotation at the top of each spec hints that there's a JSON schema that could validate this client-side, but local schema validation at runner load time would catch the same class of bug independent of editor tooling.