v1 specification authority and machine-result contract clarifications

[projectious]

Context

Phase 1 implementation is following the mandatory spec-driven development cycle introduced by PR #48. PR #49 corrected the version result contract. Independent plan review is now blocked on two authoritative specification questions.

This discussion asks project internal, as author of the v1 specification, to answer these questions and direct the corresponding specification changes. Implementation affected by these questions remains frozen until those changes are accepted into the authoritative spec.

1. Governing decision authority

The v1 README incorporates nine decisions and states that the decisions prevail if a summary conflicts with a decision body. The complete immutable decision bodies are not available in this repository and could not be located through the available project search.

Please direct one of these outcomes:

1. Add immutable copies or stable authoritative references for all nine decision bodies to the specification baseline; or
2. Amend the v1 README to state explicitly that its incorporated summaries are the complete authoritative baseline for implementation and conformance review.

The selected outcome needs to make AINFRA-DEV-006 plan review reproducible without hidden context.

2. Help and unknown-command machine results

AINFRA-CLI-002 and AINFRA-CLI-003 require command output behavior, while AINFRA-OUTPUT-001 and AINFRA-OUTPUT-010 require every command machine result to use the closed result envelope and a valid command discriminator.

The current closed schema has no discriminator or result shape for help or unknown-command responses. This makes the following behavior ambiguous:

• ainfra help
• ainfra --help
• ainfra --help
• an unknown command or invalid invocation when --format json is requested

Please direct an authoritative schema and prose change defining:

• whether help is a machine-result command;
• the canonical discriminator or discriminators;
• the success result shape for help, if supported in JSON;
• the failure envelope and discriminator for unknown or syntactically invalid invocation;
• stdout, stderr, and exit-code expectations for these cases; and
• positive and negative fixtures required for conformance.

Requested resolution

Please respond with the intended normative behavior and open or direct PRs updating every affected v1 specification file, schema, example, negative fixture, acceptance journey, and requirement disposition. Once merged, Phase 1 will rebaseline, repeat independent plan review, implement the resolved contract, and perform the mandatory whole-spec conformance review.

[projectious]

Resolution accepted.

1. Specification authority

The accepted, checked-in v1 specification commit is the complete normative implementation and conformance baseline. The nine company decision IDs remain provenance, but their external bodies are not required to implement or review ainfra and cannot silently override the repository baseline. Any later company decision changes implementation obligations only after a reviewed specification amendment updates all affected requirements, schemas, examples, fixtures, acceptance journeys, and roadmap entries.

This resolves the AINFRA-DEV-006 reproducibility problem: plan and implementation conformance are reviewed against the accepted repository commit only.

2. Help

Help is a successful, side-effect-free machine result with canonical discriminator help.

• ainfra help and ainfra --help normalize to topic ainfra.
• ainfra help <topic> and ainfra <command> --help normalize to the same group or leaf topic.
• Group topics are doctor and template; leaf topics use canonical command identifiers.
• Help exits 0 and does not load deployment configuration, discover a project, access the network, or invoke child tools.
• JSON help has a closed result containing topic, usage, summary, subcommands, arguments, and options.

3. Invalid invocation

Failures before a valid canonical command is dispatched use discriminator invocation, ok: false, result: null, at least one stable diagnostic, and exit code 2. This covers unknown commands/help topics, unknown options, malformed global options, and syntactically missing or extra arguments.

• Text mode: stdout is empty; stderr contains the diagnostic and concise usage.
• JSON mode: stdout contains exactly one invocation envelope; stderr does not duplicate the parser diagnostic.
• Exact --format json and --format=json select JSON error output anywhere before --, even if the rest of the invocation is invalid. An invalid format value cannot select JSON and therefore fails in text mode.
• Once a valid command is dispatched, semantic or execution failures keep that command's canonical discriminator.

The complete corrective change is in draft PR #51: #51

It updates the authority language, CLI and output requirements, closed JSON schema, positive examples, negative fixtures, black-box tests, acceptance journey, and development-cycle review rule. scripts/validate-v1-spec passes. Implementation work affected by these findings should remain paused until PR #51 is accepted and then rebaseline on its merged specification commit.