Skip to content

feat(multi-agent): read the role map from the config-cascade layers - #18076

Queued
melodic-automation-lanes[bot] wants to merge 3 commits into
mainfrom
work-resolve-issue/issue-17998-44959703861-1
Queued

melodic-automation-lanes[bot] wants to merge 3 commits into
mainfrom
work-resolve-issue/issue-17998-44959703861-1

Conversation

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor

Refs: #17998

Summary

Opened by the work-resolve-issue lane. The run's own summary:

The multi-agent resolver and setup now use the config-cascade layers. The user layer is the file a new role_map_file userConfig option (type file) names. The personal override is <home>/multi-agent.local.yaml. An old ~/.claude/multi-agent.yaml or .claude/multi-agent.local.yaml is still read while its new file is absent, and each run prints one note per old file naming it, its new location and /multi-agent:setup apply --migrate. When both files exist, the new one wins and the note names both. setup check names each old file. The new apply --migrate previews each move; on --write it merges the old file into the new one (keys the new file already sets keep their values and are named), reads the file back, checks the resolved roles are unchanged when the old file was the live layer, and only then deletes the old file. apply --layer user and --layer local refuse while that layer's old file exists. Design choice, per the issue's placement rule: the old user file is a nested map (roles.<role>.workloads.<w>.*) that no scalar userConfig option can hold, so it becomes one file-typed option that keeps the structure, not one option per key. The skills pass the option to the scripts as '${user_config.role_map_file}', the repository's existing pattern (formal-verification), and the scripts treat an empty or unsubstituted value as unset.

Remaining work

  • Remove the old-path reads (~/.claude/multi-agent.yaml and .claude/multi-agent.local.yaml) and their notes in a separate later change, once no old file is reported

Not verified

  • resolve-roles.test.sh and setup.test.sh were not executed: this lane can run only the named wrappers, and check-affected does not list which suites it ran. They are left to the PR's CI and were desk-checked by the review subagent
  • tidy skipped: the change touches 18 files and is over the 10-file, 300-line and 1-area cutoffs
  • the README options-reference block was written by hand in the format scripts/sync-plugin-options-docs.py emits; the generator was not run here
  • check-evals-quality could not grade the changed case.yaml (it expects JSON input); the eval cases are left to CI's eval-cases and evals-quality jobs
  • the evals that scaffold .claude/multi-agent.local.yaml (fixtures/workspace.sh, ro-rejected-model-id-layer-below) still pass during the dual-read window but now also see an old-path note; move them when the old-path reads are removed
  • apply --migrate does not move the config block in docs/conventions/multi-agent.md; it stays a delete-by-hand row as before, since it is not one of the issue's old paths

Fix

  • plugins/multi-agent/scripts/resolve-roles.sh: new --user-file option and user-config layer; personal override moved to <home>/multi-agent.local.yaml; dual-read of both old paths with one note per old file; the team file is not read a second time when it is the user layer's file
  • plugins/multi-agent/scripts/resolve-roles.test.sh: cases for new layers only, old files only (values apply, one warning each, unsubstituted option reads as unset) and both present (new wins, warning names both)
  • plugins/multi-agent/skills/setup/scripts/setup.sh: --user-file and apply --migrate [--write] (preview, merge, read back, resolve check, delete old); user layer writes to the option's file and refuses while it is unset; local writes <home>/multi-agent.local.yaml; user/local refuse beside…
  • plugins/multi-agent/skills/setup/scripts/setup.test.sh: paths moved to the new personal override; cases for the user option (unset, unsubstituted, set), old-path check rows, refusals beside old files, migrate preview and write for user and personal files, both-present merge with the kept line, and…
  • plugins/multi-agent/skills/route/scripts/route.sh: passes --user-file through
  • plugins/multi-agent/skills/route/SKILL.md: the run command passes --user-file '${user_config.role_map_file}'
  • plugins/multi-agent/skills/setup/SKILL.md: new layer paths, the option, the old-path rows, and an apply --migrate procedure; every setup.sh call passes --user-file
  • plugins/multi-agent/.claude-plugin/plugin.json: role_map_file userConfig option (type file)
  • plugins/multi-agent/reference/config.md: layer table on the contract layers, the placement basis for the file option, and the dual-read window
  • plugins/multi-agent/README.md: Configuration section on the new layers, and the generated options-reference block for role_map_file, written by hand in the generator's format
  • plugins/multi-agent/schemas/multi-agent.schema.json: descriptions name the user file and the new personal override path
  • plugins/multi-agent/evals/setup-check-shows-role-map-and-ignore-gap/{case.yaml,prompt.md,samples/recommends-local-ignore-line.json}: expect the docs/conventions/**/.local. ignore line
  • docs/contracts/config-cascade/README.md: the multi-agent Implementers rows name the userConfig file, the new personal override and the dual-read window
  • plugins/discovery/README.md: the multi-agent example names docs/conventions/multi-agent.local.yaml; the paragraph saying it was not yet migrated is removed
  • .changes/multi-agent/work-resolve-issue-issue-17998-44959703861-1-e92d82f0.md: minor fragment
  • .changes/discovery/work-resolve-issue-issue-17998-44959703861-1-92403b68.md: patch fragment

Verification

The runner ran each check from the base copy against 3d0e808:

  • scripts/check-changelog-fragments.sh --check: passed
  • scripts/check-changed-skills.sh --merge-base: passed

The run reports:

  • check-changelog-fragments: all 4 fragments valid
  • check-changed-skills: route and setup PASS, 0 errors (warnings: route description length 576 > 419, which predates this change; setup body 165 lines > 160, and its description has no 'Use when:' trigger phrasing)
  • check-affected: 15 passed, 8 skipped, 0 failed over 18 changed files. Earlier runs failed on shellcheck SC2115 (fixed with ${tmp:?}) and then on two validate-plugins warnings, a 330-character option description over the 300 budget and a spaced pipe in the argument-hint (both fixed)
  • fresh-context review subagent over the whole diff: it traced every new test assertion against the script text, and all would pass. It found five issues, all fixed: migrate could delete the live file when the convention home is .claude; migrate checked a live file alone, so cross-layer workload keys…
  • read https: //code.claude.com/docs/en/plugins-reference (Plugin manifest reference): userConfig types include file; ${user_config.KEY} is substituted in skill content; non-sensitive values are stored under pluginConfigs in user settings; each option appears as a row in /config
  • The lane run: https://github.com/melodic-software/claude-code-plugins/actions/runs/44959703861

Left out: the items under Not verified.

Related

#17998

Lane-Activity: work-resolve-issue/resolve-issue
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs

Run 44962060408, attempt 1

Field Value
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 44962060408

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/fix-ci

Run 44962703709, attempt 1

Field Value
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 44962703709

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/apply-patch

Run 44962703709, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step success
Commits pushed b93ec3c
Run 44962703709

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-security-review: 1 inline finding(s) on b93ec3c04757c184ce9c2795bb1feecc217488ca; the summary is in this lane's pull request comment.

claude-lane: claude-security-review

@github-actions

github-actions Bot commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed a39b5569726f9a912f20da60f3018eff1f9199d9: read 5 of 5 changed file(s); 1 finding(s), 0 as inline comments.

Security review (incremental, b93ec3c0 → a39b5569): PR #18076

This was a blocking-only review: the lane already reviewed an earlier head, so it reports only CRITICAL and IMPORTANT findings.

I read every hunk of the 5 files in the incremental scope: the changelog fragment, resolve-roles.sh and its test, and setup.sh and its test. None of them is on the trusted-path list. The push changes no trust control: no trusted-actor list, lane token, kill switch, token-broker signer or merge hold. No standing instruction is removed.

The change makes path handling stricter. It fixes the earlier ~/ and relative-path thread on setup.sh. That thread is settled, and its lines are unchanged since it was resolved.

  • setup.sh (L95-L98): it expands a leading ~/ against $HOME_DIR and then refuses any value that is still not absolute (die, exit 2). A write can no longer go to <cwd>/~/… or to a path that depends on the current directory.
  • resolve-roles.sh (L329-L333): it does the same expansion. For a non-absolute value it skips the user layer and adds a note, replacing any non-printable characters in the echoed value with ?.
  • Expansion: the ~/ expansion is a parameter substitution, not eval, so the value cannot inject a command.
  • Error message: the die message in setup.sh echoes the raw value to stderr. That value comes from the user's own /config, and it only appears in the user's own terminal output, so it is not a finding.

Carried forward: this push changes setup.sh and resolve-roles.sh, which read the flagged role_map_file key. Because of that, the owner's answer on the manifest flag no longer counts as settling it. The lines the post covers are unchanged and its thread is still open, so it is counted again here without a new inline comment. The new code narrows what the key's value can reach, so the severity stays IMPORTANT.

PR context: no embedded instructions to the lane. The push changes no spend.

critical-findings: 0

Manifest lines (1)

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

Unattended merge: native auto-merge leaves this pull request unarmed at head b93ec3c04757c184ce9c2795bb1feecc217488ca. No person needs to act: a lane clears this reason, and the next scheduled run judges it again.

pr-merge's gate refuses its verifier verdict (verify:missing)

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

claude-review: 1 inline finding(s) on b93ec3c04757c184ce9c2795bb1feecc217488ca; the summary is in this lane's pull request comment.

claude-lane: claude-review

@github-actions

github-actions Bot commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed a39b5569726f9a912f20da60f3018eff1f9199d9: read 5 of 5 changed file(s); 0 finding(s), 0 as inline comments.

Code review (incremental, b93ec3c → a39b556): role_map_file now expands ~/ and refuses relative paths

I read every hunk of the 5 files in .claude-lane/incremental.diff:

  • the changelog fragment
  • resolve-roles.sh and resolve-roles.test.sh
  • setup.sh and setup.test.sh

I also read the unchanged code these lines call:

  • die (exit 2) and argument parsing in setup.sh
  • the USER_HOME_DIR / NOTES / dual_read handling in resolve-roles.sh
  • the run and fixture helpers in both test files

This review was blocking only: this lane already reviewed an earlier head.

Prior finding addressed. My earlier finding was that a ~/ or relative role_map_file value went to the wrong place. Both scripts now handle it:

  • Expansion. Right after the unsubstituted-value check, both scripts expand a leading ~/ against the home variable. That is HOME_DIR in setup.sh and USER_HOME_DIR in the resolver.
  • setup.sh. Any value that is still not absolute is refused with die, which exits 2 and prints "set an absolute path in /config". This runs before LOCATE, OLD_USER_SAME and any write or migrate, so mkdir -p '~' can no longer happen.
  • Resolver. It skips the user layer and leaves a note with the non-printable characters masked. dual_read then gets an empty path and reports the layer absent, so routing keeps working.
  • Tests. Both test files gain a tilde case and a relative case. The assertions are exact: the expanded path, exit 2, the note text, and the absent layer row.

The changelog fragment now describes this behaviour accurately. That thread is resolved, and no lines under it changed since the resolution.

Blocking findings. None in this increment.

Not verified. I did not run the test suites because this lane has no shell. The PR's pass counts (95/95 and 115/115) are the author's claim and I have not checked them.

Closing issue. The PR context file has no closing-issue section (the PR says Refs: #17998), so there were no acceptance criteria to check.

Loosened checks. The new test cases only add assertions; nothing was loosened.

  • Loosened checks would be marked: fail. That is the default, because the prompt gave no loosened_check_verdict: or loosened_check_patterns: line. Patterns: 0.
  • The prompt gave no loosened_check_decision_record: line, so I did not check the citation requirement.

Paved paths. There is no paved-path row, so there is nothing to report.

Settled threads.

  • The plugin.json option-surface thread: the owner accepted it, and nothing under it changed.
  • The setup.sh ~/relative thread: resolved by this push.

Neither thread contains embedded instructions.

Spend. None.

Verifier dropped 0 of 0 candidates.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/address-feedback

Run 44968123520, attempt 1

Field Value
Model rung 0
Leg handoff
Run job success
Activity step skipped
Commits pushed none (read lane)
Run 44968123520

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/publish-feedback

Run 44968123520, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step skipped
Commits pushed none recorded
Run 44968123520

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

The unattended merge path is about to arm native auto-merge at head b93ec3c04757c184ce9c2795bb1feecc217488ca, the head its arming checks judged. The arm fails if the head moves first.

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

Merge-Risk: max=HIGH demote=true head=b93ec3c04757c184ce9c2795bb1feecc217488ca rubric=10.4.6 rater=claude-opus-5-5 checker=claude-opus-5-5

@kyle-sexton

Copy link
Copy Markdown
Member

Risk review (R18) of the HIGH demote=true rating at b93ec3c. Its one HIGH reason is Reversibility: setup.sh apply --migrate --write deletes the old ~/.claude/multi-agent.yaml, .claude/multi-agent.local.yaml and .claude/multi-agent.yaml and rewrites the new file whole, so a revert would strand values at the new paths. Accepted: these are the operator's own role-map settings, never a credential; the delete runs only after a preview and an explicit yes; and the change alters no permission, trust boundary, security control or cost. A fix for the open role_map_file path finding (thread eQoo) is being pushed. Its new head gets its own rating, and this review applies unless that rating adds a stop-list reason.

The role_map_file option reached setup.sh and resolve-roles.sh verbatim,
and both skills pass it single-quoted, so a value of ~/role-map.yaml made
apply --layer user --write create <cwd>/~/role-map.yaml, apply --migrate
move the old user file there, and the resolver read the user layer only
from that cwd. Claude Code's plugins reference does not say it expands ~
or makes a file-type value absolute, and both scripts also take the value
from --user-file.

Both scripts now expand a leading ~/ against their home variable after
the unsubstituted-value check. setup.sh refuses any other non-absolute
value with exit 2 before computing LOCATE and the old-file comparison.
The resolver skips the user-config layer with a note instead of exiting,
matching how it skips a malformed layer, so one bad option does not break
routing for every skill.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RAoAtUnz4WHB5auUnwQYq7
@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-unblock/report-escalation

Run 44974337302, attempt 1

Field Value
Model rung 0
Leg base
Run job success
Activity step skipped
Commits pushed none recorded
Run 44974337302

Failed GitHub API calls

No failed call recorded by the run job's scripts.

@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 22, 2026
Any commits made after this event will not be merged.
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Nov 22, 2026
@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

The unattended merge path is about to arm native auto-merge at head a39b5569726f9a912f20da60f3018eff1f9199d9, the head its arming checks judged. The arm fails if the head moves first.

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

Merge-Risk: max=HIGH demote=true head=a39b5569726f9a912f20da60f3018eff1f9199d9 rubric=10.5.0 rater=claude-opus-5-5 checker=claude-opus-5-5

@melodic-automation-lanes
melodic-automation-lanes Bot added this pull request to the merge queue Nov 22, 2026
Any commits made after this event will not be merged.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant