[scout] Tighten custom provider registry validation

[s-hiraoku]

Summary

Tighten custom provider registry validation so invalid provider configuration fails explicitly instead of being silently accepted as a default.

Target repository and affected paths

• Target repository: kaizen-agents-org/builder-agent
• Affected components: custom provider registry parsing and Kaizen Loop integration provider selection
• Affected paths:
  • src/agents/AgentRunner.ts
  • test/builder-agent.test.js
  • README.md
  • docs/provider-fallback-architecture.md

Observed evidence from default branch

Default branch inspected: origin/main at 49509536a47c8e8f3ef878a003606aa5cbde0d0f.

• README.md documents KAIZEN_AGENT_PROVIDERS and KAIZEN_AGENT_PROVIDERS_FILE as the custom backend provider registry. It says provider entries support a bounded set of fields and that output is stdout or last-message.
• docs/provider-fallback-architecture.md says the registry accepts either a provider object or { "providers": { ... } }, and lists the intended provider registry fields as part of the fallback architecture.
• src/agents/AgentRunner.ts currently normalizes provider entries without checking for unknown top-level provider fields. createCustomProvider() casts the entry to AgentProviderConfig and ignores unsupported keys.
• src/agents/AgentRunner.ts currently treats any output value other than last-message as stdout with const output = config.output === "last-message" ? "last-message" : "stdout";. A typo such as "last_message" silently changes how payloads are read.
• test/builder-agent.test.js covers valid custom provider env/file cases, prompt templates, health checks, and fallback behavior, but does not cover rejecting unknown provider keys or invalid output enum values.

Recommended action

Make provider registry validation match the published integration contract:

1. Reject unknown provider entry fields with an actionable error listing the unsupported keys.
2. Reject invalid output values instead of defaulting them to stdout; keep output omitted as the documented default.
3. Apply the same validation to nested healthCheck entries if unsupported keys are present there.
4. Add focused tests for KAIZEN_AGENT_PROVIDERS and KAIZEN_AGENT_PROVIDERS_FILE invalid configurations.
5. Keep the existing valid examples and default behavior passing.

Documentation basis

• .github/docs/architecture.md, "Standalone And Integrated Use": builder-agent should remain useful on its own while keeping integration boundaries explicit; strict provider configuration helps keep that boundary predictable.
• .github/docs/implementation-status.md, "builder-agent": the current hardening focus is adapter behavior and the quality of artifacts consumed by kaizen-loop and verifier.
• .github/docs/repo-improvement-scout.md, "What It Looks For": builder-agent scout scope includes adapter/CLI behavior, backend/model selection, fallback behavior, and build-result schema fidelity.
• README.md, "Kaizen Loop Integration": provider registries are a documented runtime contract and list output as stdout or last-message.
• docs/provider-fallback-architecture.md, "Implemented Direction": provider registry, fallback, health-check, and output-adapter behavior are intentional architecture, so typos should not silently alter fallback behavior.

Duplicate-check summary

Checked open issues and PRs in kaizen-agents-org/builder-agent for provider registry validation, unknown provider fields, invalid provider output, KAIZEN_AGENT_PROVIDERS_FILE, and related custom provider terms. Existing open issues #75 and #76 cover test organization and missing failure-class tests, not strict provider registry validation. No open PRs currently cover this target repository work.

Also searched open issues and PRs in .github, kaizen-loop, and verifier for related builder-agent provider registry validation work; none appeared to own this same repo-local change.

Related issues or PRs

• Related but not duplicate: Split test coverage per module after the JS-to-TS migration #75 tracks splitting test coverage by module.
• Related but not duplicate: Add missing test coverage for command_missing/timeout/rate_limited failure classification #76 tracks missing command_missing / timeout / rate_limited failure-class tests.

PR linkage requirement

The implementation PR for this issue must target the repository default branch, include Closes #78 in the PR body for same-repository work, and verify gh pr view <pr> --json baseRefName,closingIssuesReferences,isDraft before reporting the PR ready. Do not rely on a PR title, branch name, or issue comment as proof that GitHub will close the issue on merge.

[s-hiraoku]

Kaizen Loop progress

PR created (#89); monitoring CI and review feedback with pr-guardian.

[s-hiraoku]

Kaizen Loop result

Result	Failed
Reason	CreatedPullRequestValidationError: Created pull request #89 failed readiness validation: Created pull request #89 is not ready: closing issue reference #78 was not recognized by GitHub
Agent	builder (attempt 1/3)
Verification	not configured

Summary

CreatedPullRequestValidationError: Created pull request #89 failed readiness validation: Created pull request #89 is not ready: closing issue reference #78 was not recognized by GitHub