fix(multi-agent): source every role default from an upstream statement that states it

[kyle-sexton]

Requested by Kyle · project thread

Closes #6265

Summary

Before: every role in plugins/multi-agent/reference/defaults.yaml cited workflows#cost (plus the bundled /workflow-authoring skill) for both its model and its effort. That section names no effort level and sets no role's model. /multi-agent:route printed the values as resolved routing, and /multi-agent:audit-defaults only asked whether a source "still supports" a value, so it had no verdict for a pointer that never stated the value.

After: each role's model and effort records basis_<field>. An upstream basis names the section (pointer_<field>) and the statement in it (claim_<field>). A judgment basis gives a reason_<field>. route prints a basis per value. audit-defaults sends judgment values to no finder and lists them with their reasons, and it reports unsupported when a cited section states neither the value nor a rule the value follows from.

Fix

Sources, each read live on 2026-10-11 with the plugin's own scripts/docs-raw.sh (fresh raw read):

Role.field	Value	Basis	Source
orchestrator.model	inherit	upstream	cost guide: orchestrator strategy: the frontier model holds the loop and produces the plan and synthesis
orchestrator.effort	high	judgment	No upstream page states an orchestrator effort.
worker.model	inherit	judgment	The cost guide delegates to lower-cost workers. The fan-out guard applies that under a frontier session; no cheaper alias is fixed otherwise.
worker.effort	medium	upstream	model-config: choose an effort level: row for day-to-day engineering with a clear scope
verifier.model	inherit	judgment	No upstream page states a verifier model.
verifier.effort	high	upstream	same table: row for work where verification matters or edge cases are likely
retrieval.model	sonnet	upstream	workflows: cost: use a smaller model for stages that don't need the strongest
retrieval.effort	medium	judgment	No upstream page states an effort for lookup. It stays at the sonnet default rather than the quick-exchange level.

No model or effort value changed, so the issue's "values that change" CHANGELOG list is empty; the fragment says so and names each value's new source. As-of dates are 2026-10-11, and each role's recheck trigger names the section its values hang on.

Code:

• scripts/resolve-roles.sh: adds a basis: {model, effort} per role. Values are upstream or judgment from the bundled layer, config when a consumer layer supplied the value, and unrecorded when the bundled entry names none. basis_*, claim_* and reason_* are bundled-only provenance, like pointer*. A consumer layer that sets them is ignored with a note.
• skills/audit-defaults/scripts/list-pointers.sh: passes the new keys through as provenance.
• workflows/drift-audit.js: adds the new unsupported verdict. It goes through the skeptic panel like drifted, keeps its value, and the diff proposes basis_<field>: judgment plus a reason_<field> placeholder. Judgment values are split off before the finders and returned as judgment.
• route and audit-defaults SKILL.md, reference/config.md and README describe the basis.
• Changelog fragment: multi-agent, minor.

Defaults I chose without a recorded decision:

• Fan-out guard values (fanout.*, frontier) are left as they are. The issue is about role defaults, and fix(multi-agent): recheck fanout and worker defaults, fix audit-defaults step 3 #6904 edits those lines.
• The generic pointer and pointer_cost keys on roles are removed in favor of the per-value pointers. pointer_skill and pointer_spawn stay as mechanism pointers.
• Worker model stays inherit (judgment) even though the cost guide puts workers on lower-cost models. Changing it would change routing, which is Kyle's call.

Verification

• bash plugins/multi-agent/scripts/resolve-roles.test.sh: 60 cases, 0 failed. New cases cover per-role basis (every shipped role has an anchored pointer plus a claim, or a reason), basis in the resolved JSON, config for a consumer value, an ignored consumer basis key, and unrecorded.
• node --test plugins/multi-agent/tests/drift-audit.test.mjs: 39 pass. Both new tests (judgment split, unsupported verdict and diff) fail against origin/main's workflow and pass with this change.
• scripts/affected-tests.sh --base origin/main --run: every selected suite passes except skills/audit-defaults/scripts/list-scripts.test.sh. Its five failures are all list-targets.sh cases (awk: runaway regular expression) and come from this host's mawk. Main's own copy fails the same five here, and this PR does not touch list-targets.sh. The list-pointers cases in that suite pass.
• scripts/check-changed-skills.sh origin/main: route passes. audit-defaults fails only on that same list-scripts.test.sh.
• shellcheck on the changed scripts, markdownlint on the changed Markdown, check-purged-em-dashes.sh, validate-plugins.sh, check-changelog-fragments.sh --check / --check-required origin/main and check-changelog-parity.sh --check: all pass.

Related

• fix(multi-agent): recheck fanout and worker defaults, fix audit-defaults step 3 #6904 (open draft) edits the worker and fanout as_of/recheck lines in defaults.yaml and the audit-defaults SKILL.md step 3. The two PRs will conflict in defaults.yaml whichever merges second. This PR leaves fanout alone, so a rebase means taking this PR's roles block and fix(multi-agent): recheck fanout and worker defaults, fix audit-defaults step 3 #6904's fanout lines.
• feat(instruction-placement): look up loading mechanics upstream at run time and gate stale records #6100 (the same idea for instruction-placement)

🤖 Generated with Claude Code

https://claude.ai/code/session_01L8KdG7fWg2YrErVYWtohmR

---

Generated by Claude Code

[kyle-sexton]

ci-status is red because this PR is a draft, not because of the change. On a draft every lint and test lane skips (lint-repo, test-bash, test-node, test-python, check-skills, check-plugins), and the aggregate counts a skip as not passing. See .github/workflows/pr-require-checks.yml:507-513.

The lanes run once the PR is marked ready. That flip waits for Kyle, because it also starts the review lanes. Until then, the local runs listed under Verification in the PR body are the signal.

---

Generated by Claude Code