[Danathar]

Summary

A contributor acting as an agent role now gets two things that #17310 left out of the role guidance. The first is the # Relevant Knowledge section, primed from their one assigned issue. The second is the AGENTS.md and skills of the repository that issue is in. Before this change, the guidance had no knowledge section at all, and it always carried the role's primary repository's AGENTS.md, whatever repository the task was in. Priming for a contributor records nothing for the resident agent. Resident kicks are byte-identical (the #17310 goldens still pass).

Refs #17310

What went wrong

#17310 swapped the resident agent's whole kick for the role's guidance (Scheduler.BuildAgentGuidance(role)). The guidance knew only the role, not the task, so two parts of the role prompt were wrong:

• No Relevant Knowledge. The guidance render skipped knowledge priming entirely. Priming took its keywords from the resident agent's queue, and it also recorded a kick summary and the primed-fact list for the resident agent (✨ kick priming: one log line per kick with knowledge bytes injected and entries skipped for the cap #17049, ✨ knowledge: LLM ranking decorator over the mid-task adviser — rank-only, fail-closed, shadow/rank/holdout (advisor phase 2, slice 3) #17155, ✨ knowledge advisor: surface scoped knowledge mid-task when an agent's work enters a new scope #17052). So 🐛 [v6] contribute: a role-delegated task carries the role's guidance, not the resident agent's work list #17310 turned it off rather than record a kick that was never sent.
• The wrong repository's instructions. AGENTS.md and skills were read from agentsRepoRoot(primaryRepo). On the projectbluefin hive, kylerankin acting as scanner worked on Hive acceptance infrastructure: automate Utah boot and runtime evidence before landing system changes projectbluefin/common#1614 and on finpilot#636. Both prompts carried the instructions of scanner's primary repository, not those of common or finpilot.

What changes

• The guidance is built for the assigned task. The new Scheduler.BuildAgentGuidanceForTask(role, task github.Issue) takes the assigned issue: its repository, number, title, body and labels. BuildAgentGuidance(role) stays, as the form with no task.
• Both callers pass the task. roleKickPrompt(role, task) builds the issue from what each caller already holds. For a role-delegated assignment (contribute_select.go), that is the chosen candidate's repository, number, title, body and labels. For standby dispatch (contribute_standby_dispatch.go), it is the ready-queue item's repository, number, title and labels.
• Relevant Knowledge comes from that one issue. primeKnowledgeStats is split:
  • renderKnowledge is the shared core. It runs the query, the role's knowledge scope, the kick context and the byte cap. It records nothing.
  • The resident wrapper, primeKnowledgeStats, records the kick summary and primed slugs exactly as before.
  • The new primeKnowledgeForTask calls only the core.
    The query itself has no usage counter to skip: PrimeForKick reads usage counts for ranking but never writes them. The only per-agent state it touches is the cap-log dedupe key, which only picks a log level.
• AGENTS.md and skills come from the task's repository. They are read from agentsRepoRoot(task.Repo). That uses the same sources as a resident kick (a checkouts_dir checkout, then policies.local_dir, then the GitHub copy via SetAgentsMdFetcher) and the same size caps. If the task names no repository, the primary repository is used, as today.
• Unchanged from 🐛 [v6] contribute: a role-delegated task carries the role's guidance, not the resident agent's work list #17310: no work lists, no dynamic tail, no classification sweep. ${WRITING_GUIDE} already renders in guidance mode. A test now pins it.

Files

• src/pkg/scheduler/role_guidance.go: BuildAgentGuidanceForTask, and the roleGuidance value that carries the task into the render.
• src/pkg/scheduler/templates.go: substituteTemplate takes *roleGuidance instead of a bool (nil means a resident kick). It primes from the task and picks the instructions repository.
• src/pkg/scheduler/kick_priming.go: renderKnowledge (the core) and primeKnowledgeForTask.
• src/pkg/dashboard/contribute_agent_roles.go, contribute_select.go, contribute_standby_dispatch.go, deps.go: the task is passed through, and the interface method becomes BuildAgentGuidanceForTask.
• src/docs/contributor-trust-and-roles.md: "What a contributor receives in a role" now covers both points. src/docs/labels-and-control-signals/reference.md: one line cite moved by 3 lines.
• changelog.d/fixed-role-guidance-task-knowledge.md.

Tests

New tests. Each one failed on the v6 tip (a5c5117) and passes here:

• TestBuildAgentGuidanceForTaskCarriesTaskRepoAndIssueKnowledge (scheduler; scanner and quality). For a task in docs (not the primary repo console), the guidance has # Relevant Knowledge with the fact matching the issue, docs' AGENTS.md and not console's, and the writing guide. It has none of the resident-only text from 🐛 [v6] contribute: a role-delegated task carries the role's guidance, not the resident agent's work list #17310's list. The resident agent gets no kick summary, no primed slugs and no classified journeys. On the tip, with a shim that ignores the task: missing Relevant Knowledge, missing the task fact, missing the task repo's AGENTS.md, and it carried the primary repo's. Forcing the guidance path onto the recording primer makes the kick-summary and primed-slugs assertions fail, so they catch what they should.
• TestRoleDelegatedTaskGuidanceCarriesTaskRepoAndIssueKnowledge (dashboard; scanner and quality, through selectTask) and TestStandbyDispatchGuidanceCarriesTaskRepoAndIssueKnowledge (dashboard, through AutoDispatchStandby). Both check for the task repo's AGENTS.md, the issue's knowledge and no primary-repo AGENTS.md. They reuse 🐛 [v6] contribute: a role-delegated task carries the role's guidance, not the resident agent's work list #17310's counting scheduler and its banned-text list (MERGE-ELIGIBLE, CI-FAILING, ACTIONABLE ISSUES, ACTIONABLE PRs, hive-merge, Begin now, RED MAIN …), so there are no resident kicks and no classified journeys. On the tip, both fail on the same four assertions.
• TestBuildAgentGuidanceForTaskWithoutRepoFallsBackToPrimary pins the fallback (it passes on the tip too, by design).
• TestResidentKickGoldensUnchanged and 🐛 [v6] contribute: a role-delegated task carries the role's guidance, not the resident agent's work list #17310's guidance tests still pass.

Full runs: go test ./pkg/dashboard/... ./pkg/scheduler/... ./pkg/policies/..., go vet on the same packages, check-docs-citations.py, check-docs-links.py.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign kellyaa for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[hivecommons-hive]

Review follow-ups (below review.backlog.min_severity: P2)

Non-blocking findings below the backlog filing line are listed here instead of as issues, one comment per PR, updated in place. Tick them off as they are fixed; set review.backlog.min_severity: P3 to file every finding.

• P3 info correctness — Guidance renders share the resident agent's primer cap-log dedupe key (src/pkg/scheduler/kick_priming.go:368): renderKnowledge keys primerCapLogged on agentName|cap (kick_priming.go:368-371), so a contributor's task-primed render with a different omitted-fact count flips the key and the next resident kick log…

[hivecommons-hive]

Docs-currency pass at ac7feb9. The new "What a contributor receives in a role" text matches the code (extractKeywords uses labels + title words, kick_priming.go:529-554; roleGuidance.instructionsRepo falls back to primary, role_guidance.go:30-39), and the moved templates.go:341-346 cite lands on the filterByLane block. Two small advisories, neither blocking:

1. src/docs/agents-md.md:30-31 now describes only one of two paths. It still says "The kick reads the primary repo's AGENTS.md", with no mention that a role-guidance render (templates.go agentsRepoRoot(guidance.instructionsRepo(primaryRepo))) reads the assigned task's repo. An operator reading the AGENTS.md page to learn which repo's file is injected will not find the new rule.

   never another repo's. A resident kick reads the **primary repo's** `AGENTS.md`, since
   that is the repo the kick's instructions are about. A contributor's role guidance
   reads the **assigned task's repo** instead (falling back to primary when the task
   names none); see [What a contributor receives in a role](contributor-trust-and-roles.md#what-a-contributor-receives-in-a-role).
   

2. src/docs/contributor-trust-and-roles.md:136 lists the lookup order as "project.checkouts_dir first, then the GitHub copy", skipping the policies.local_dir step that agentsRepoRoot tries in between (kick_priming.go:45-52; the PR body lists all three). Since the sentence says "the same way as for a resident kick", consider either adding the middle step or linking to agents-md.md, which already documents the full order.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Review findings from adjudicator (folded here because this head already carries its hive review):

Security perspective (read at head ac7feb9a): no in-scope blocker.

Checked: task.Repo fed to agentsRepoRoot is repo.Full from the hive's configured repo list / ready queue (src/pkg/dashboard/contribute_select.go:962,1106, contribute_standby_dispatch.go:322), not contributor-supplied, and the remote root still refuses unsafe segments (src/pkg/scheduler/kick_agentsmd_remote.go:76-80,129-131). The task repo's AGENTS.md reaches a contributor who is already minted a token for that repo (contribute_select.go:1397), so no new exposure there.

One advisory (low, non-blocking):

primeKnowledgeForTask → renderKnowledge applies the role's agent_scopes entry unchanged (src/pkg/scheduler/kick_priming.go:343-349). When that scope opts into drafts, DraftAuthors = kickDraftAuthors(cfg, agentName) (lines 386-406) includes unreviewed draft facts authored by the resident agent and by the hive's owner logins. Those now render into an external contributor's prompt, which #17310 had (incidentally) stopped. This restores pre-#17310 behaviour rather than widening it, but the doc line at src/docs/contributor-trust-and-roles.md:135 ("with the role's knowledge scope") doesn't call out that operator drafts are included. If you'd rather keep drafts resident-only, a small switch does it:

--- a/src/pkg/scheduler/kick_priming.go
+++ b/src/pkg/scheduler/kick_priming.go
@@ func (s *Scheduler) primeKnowledgeStats(agentName string, issues []github.Issue) knowledgeInjection {
-	inj, slugs := s.renderKnowledge(primer, cfg, agentName, issues[:limit])
+	inj, slugs := s.renderKnowledge(primer, cfg, agentName, issues[:limit], true)
@@ func (s *Scheduler) primeKnowledgeForTask(agentName string, task github.Issue) knowledgeInjection {
-	inj, _ := s.renderKnowledge(primer, cfg, agentName, []github.Issue{task})
+	// A contributor is not the resident agent: unreviewed drafts stay resident-only.
+	inj, _ := s.renderKnowledge(primer, cfg, agentName, []github.Issue{task}, false)
@@
-func (s *Scheduler) renderKnowledge(primer *knowledge.Primer, cfg *config.Config, agentName string, issues []github.Issue) (knowledgeInjection, []string) {
+func (s *Scheduler) renderKnowledge(primer *knowledge.Primer, cfg *config.Config, agentName string, issues []github.Issue, allowDrafts bool) (knowledgeInjection, []string) {
@@
-		if knowledge.ListsDraft(sc.IncludeStates) {
+		if allowDrafts && knowledge.ListsDraft(sc.IncludeStates) {
 			agentScope.DraftAuthors = kickDraftAuthors(cfg, agentName)
 		}

(If drafts are intended for contributors too, a sentence in the doc line above would settle it.)

Evidence bundle `#17315ac7feb9` sha256:ab005046548cc22a20c2432712f6fb247bf057d7dc0f3b06de500f5dee1081cc — download from the dashboard or `hivectl review evidence #17315`.

[hivecommons-hive]

merged by Hive trusted-author auto-merge: author @Danathar holds role owner and GitHub permission maintain on repo; CI green at ac7feb9.

[hivecommons-hive]

Quality test-review @ac7feb9 — the behaviour change ships with tests that fail without it; no gap to file.

• TestBuildAgentGuidanceForTaskCarriesTaskRepoAndIssueKnowledge (scheduler) asserts the three things the fix adds — # Relevant Knowledge primed from the one issue, the task repo's AGENTS.md, and the absence of the primary repo's — plus the three things it must not add (KickSummary, KickPrimedSlugs, classified journeys for the resident). Pre-fix guidance had no knowledge section and always carried the primary AGENTS.md, so the positive and negative assertions both fail on v6 without BuildAgentGuidanceForTask.
• ...WithoutRepoFallsBackToPrimary pins the compatibility path (github.Issue{} → primary AGENTS.md, no knowledge), which is what keeps BuildAgentGuidance callers unchanged.
• Dashboard side (TestRoleDelegatedTaskGuidance…, TestStandbyDispatchGuidance…) repeats the same assertions through selectTask and AutoDispatchStandby, so the roleKickPrompt(role, task) plumbing is exercised end to end, not only the scheduler unit.
• patch-coverage and coverage are green at this SHA.

Not blocking, FYI only: the dashboard tests check msg.Repo == "myorg/repo1" before asserting prompt content, so a regression that routed the task to the right repo but rendered the wrong AGENTS.md would still be caught by the PRIMARY-REPO-INSTRUCTION negative assertion — good.

---

🐝 Hive Agent: quality | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=quality backend=copilot model=claude-fable-5.1 copilot=1.0.88