Add a read-only setup status mode that diagnoses configuration and missing domain skills

[fastner]

Problem

Several faults stay invisible until they happen to affect a run, and even then they appear only as a side note:

• a dead or stale setup marker;
• several project-setup ADRs that tie in the locator's ranking;
• a tracked visibility | hidden row that is ignored;
• a transitional config.json still in use;
• invalid table values, which fall back to a safe default "for the run" (src/shared/config-migration.md, last paragraph);
• retired rows that will stop the next run.

Missing central skills are also invisible. When the declared domain owner for a tool is not installed, or is excluded through skills.exclude / skills.enabled: false, the tool degrades to its minimal generic fallback (src/shared/skill-discovery.md point 6, src/shared/central-reasoning-delegation.md "Authority contract and minimal fallback"). Point 7 only asks a run to name the skills it used. Nothing tells the user in advance that a declared owner is missing. The ownership manifest (docs/developer-guide/skill-ownership.json) exists only in the repository and is not shipped.

setup is the owner of the configuration, but it has no way to diagnose without writing. Step 0 (src/tools/setup.md "Step 0: Resolve the setup mode") accepts only empty, profile, express, guided and hidden. It rejects any other argument.

Proposal

Add a sixth Step 0 form, setup status. It runs no step from Step 1 on, poses no ask fence, and writes nothing: no .gitignore or info/exclude edit, no ADR, no marker, no migration, and no runtime-directory migration. It reports:

1. Configuration: the resolver result from Resolve the Effective Flow configuration with a deterministic runtime script #484, listing the winning source (step, path, envelope language, hidden or standard) and every diagnostic with the setup action that fixes it.
2. Ignore state: whether .effective-flow/ is ignored in the location the current visibility requires.
3. Domain owners: for each tool, every central skill that the shipped ownership projection lists as delegate owner. Each one is reported as available, not installed, or disabled by configuration, together with the consequence ("<tool> runs its minimal fallback").
4. Version: the installed {{VERSION}} compared with the latest published release. The release lookup is optional and unauthenticated. When it fails, the report says "could not check" and the run does not fail.

For point 3, the build projects a minimal runtime JSON from skill-ownership.json into every target. It contains the skill, the consumer and the classification, and nothing else. A build guard keeps that projection equal to the manifest. The shipped text must not link to repository-only docs.

Non-interactive runs produce the same report. The report ends with a next-steps recommendation of setup only when it found a problem that setup can fix.

Acceptance criteria

• setup status performs no write of any kind. A test asserts that the status branch contains no write, ask or migration step.
• Every resolver diagnostic from Resolve the Effective Flow configuration with a deterministic runtime script #484 maps to a reported line with a remediation.
• A declared delegate owner that is missing or excluded is reported for each consuming tool.
• The version comparison degrades to "could not check" when the lookup fails.
• Unknown arguments still print all accepted forms, now six, and stop.
• The build ships the ownership projection in all three targets, and a guard reconciles it with skill-ownership.json.
• docs/user-guide/tools-setup.md and troubleshooting.md document the mode.

Scope

src/tools/setup.md (Step 0), a new lazy fragment such as src/shared/setup-status.md, src/shared/next-steps.md (optional setup row), build.mjs (projection, guard, budget), test/workflow-contracts.test.mjs (the test "setup routes only the empty, profile, express, guided, and hidden invocations before mutation"), and docs/user-guide/.

Constraints and notes

• Budget: setup is at 1918/1918 built lines. The status branch must be a lazy-include behind the Step 0 classification, like setup-profiles, and the Step 0 addition is re-measured.
• Ownership: diagnosis of Effective Flow configuration and skill wiring is orchestration, so the ownership check finds no central playbook to delegate to.
• setup stays the sole writer. status must never offer to fix anything inline, and it only names the setup form that would.
• Open question: which release source to query (forge releases or tags) without requiring authentication.
• setup is not in the merge-gate load set. If the work touches config-migration.md or next-steps.md, the merge-gate eval evidence goes stale and must be re-recorded before the next release.

Related

• Depends on Resolve the Effective Flow configuration with a deterministic runtime script #484.
• Add a read-only next tool that reports where work stands and decide the future of open-plans #486 reports work state. This mode reports configuration health, so keep the two apart.