[clubanderson]

Fixes #14575

What

Every kick, on every backend, now opens with a HOUSE STYLE section — how changes are to be made (smallest complete diff, follow existing patterns, tests for behaviour changes, keep names stable, DCO) — as distinct from what to work on (the kick body) and the repo's own rules (AGENTS.md).

Precedence: repo HIVE_STYLE.md (read from the project.checkouts_dir checkout, same root as AGENTS.md) > hive default (project.style inline, else project.style_file) > built-in.

Safety

• Each candidate is capped at project.style_max_bytes (default 4096, min 512) and skipped whole when oversize — the next source applies; never clipped.
• The repo file is untrusted input: scanned with pkg/ioscan at the issue-body policy and refused whole on a block; falls through to hive/built-in. Operator-supplied text is trusted. Every skip writes a house_style_skip audit line (agent, source, path, reason); ioscan blocks also write their usual ioscan_block lines.
• The section is static per agent so prompt caching is unaffected (TestKickLayoutStaticPrefixIsCacheable updated to assert it leads the static prefix).

Dashboard

Agent card and detail pane show a style field (repo / hive / built-in), read back from the kick's HOUSE STYLE (source: …) header — so it reports what was actually sent. /api/status exposes agents[].styleSource. CSS uses existing tokens only.

Docs

New docs/house-style.md; operator-reference.md rows for project.style, style_file, style_max_bytes; agents-md.md and documentation-map.md cross-links; hive.yaml.example; api-reference.md; changelog fragment.

Tests

ok  pkg/housestyle   coverage: 100.0%   (new package; precedence, size cap, scanner refusal, unreadable/blank file, SourceFromKick)
ok  pkg/scheduler    coverage: 93.0%    (built-in leads every kick; repo > hive; oversize audited + raised cap; ioscan refusal + audit lines; hive text not scanned; ioscan off → repo applies)
ok  pkg/config       coverage: 90.5%    (golden updated with the three new keys)
ok  pkg/dashboard    (StyleSource from LastKickMessage)
ok  pkg/dashboard/webstatic (style ratchet)

Non-goals (follow-ups noted on the issue)

• No GitHub Contents API fetch of HIVE_STYLE.md when there is no checkout — same posture as AGENTS.md.
• No per-agent style; the point is one voice.

Evidence (screenshots)

Captured against hive's own spoke (hive-oke) via a local proxy serving this branch's SPA; the deployed build predates styleSource, so the proxy injects the precedence outcome a hive with a repo HIVE_STYLE.md reports.

Agent card — new style field (repo):

Agent detail pane — STYLE field:

Tests: go test ./pkg/housestyle ./pkg/scheduler ./pkg/dashboard/... green locally (see PR checks).

[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 danathar 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

[github-actions]

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR	Title	Relation	Files
#14524	✨ feat(hub,agent): Hub-coordinated live CLI session pool for multi-tenant runner capacity	same files	src/docs/api-reference.md
#14595	✨ feat: mark lanes unauthorized when the App lacks rights for the next step	same files	src/pkg/dashboard/static/index.html
#14573	✨ feat(dashboard): show a draft pill in the activity tracker	same files	src/pkg/dashboard/static/index.html
#14597	🐛 fix(dashboard): show the fleet running · $/hour figure in the visible Governor grid	same files	src/pkg/dashboard/static/index.html
#14590	✨ feat(evidence): mediated-vs-unmediated outcome benchmark report	same files	src/docs/documentation-map.md

[hivecommons-hive]

Read at ad63b34 against v5 merge-base 7d61076. The resolver and kick wiring look correct to me; two low-severity notes and the rebase below.

Verified

• pkg/housestyle.Resolve (housestyle.go:114-150): repo → hive → built-in, each candidate used whole or skipped with a recorded Skip; missing files are silent, unreadable ones audited (:155-170). Cap floors at 512 and defaults to 4096 as documented.
• scheduler.resolveHouseStyle (kick_housestyle.go:30-62) scans only the repo candidate, via ioscan.ScanInputFrom(…, SurfaceIssueBody, policy), and reuses recordIoscanBlock/ioscanAuditUser/auditLogger from ioscan_enforce.go; the repo root comes from the same agentsRepoRoot the AGENTS.md primer uses (kick_priming.go:36). addHouseStyle is first in staticSeams (kick_layout.go:83), so after the reverse application it is the first section under the kick header, as the PR says.
• Dashboard: StyleSource is derived from proc.LastKickMessage (status_builder.go:1166) via SourceFromKick, which only accepts the three known values — reports what was actually sent, as claimed.

Low — inline oversize skips style_file instead of falling through to it. housestyle.go:131-141: when project.style is non-empty but over the cap, the else if in.HiveFile != "" branch is never reached, so the result is built-in even when style_file is set and valid. docs/house-style.md:28-29 says "when one is skipped the next applies"; an operator with both set would reasonably expect the file. TestResolveSizeCap (housestyle_test.go:66-68) pins the built-in outcome, but with no HiveFile, so it does not cover this case. Cheap fix: drop the else and let the file branch run when inline was skipped.

Low — settings parity satisfied by tooltip text only. project.style and project.style_file pass TestSettingsDialogReferencesEveryHiveYAMLLeaf because the strings appear in a tooltip (static/index.html:13526), not because the Settings dialog has a control for them, while project.style_max_bytes is allowlisted with # TODO #14575 (settings_parity_allowlist.txt:345). Either all three belong on the allowlist under the same TODO, or all three get a control; as is, the gate reports two of them as "referenced" that an operator cannot edit from the UI.

Rebase: four files in this diff also changed on v5 since the merge-base and GitHub reports the PR as conflicting: src/docs/api-reference.md, src/pkg/dashboard/server.go, src/pkg/dashboard/static/index.html, src/pkg/dashboard/status_builder.go. CI (test, coverage, build) did not run on this head for that reason; the pkg/dashboard tests in the body are therefore unconfirmed by CI.

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

[hivecommons-hive]

Read pkg/housestyle, the scheduler seam and the dashboard readback against v5 at merge-base 7d61076. The logic looks correct to me; the only thing between this and green is the rebase.

What I verified:

• Precedence and fall-through (housestyle.go:108-144): a repo file that is oversize, unreadable, blank or scanner-blocked records a Skip and falls to hive inline → hive file → built-in; nothing is ever clipped, and Resolve cannot return empty text. Cap (:96-104) applies the 4096 default / 512 floor the docs state.
• Ordering: addHouseStyle is first in staticSeams (kick_layout.go:83); since seams insert after the header and are applied in reverse, it ends up first in the static prefix, exactly as TestKickLayoutStaticPrefixIsCacheable is updated to assert.
• Dashboard readback is real, not cosmetic: SourceFromKick parses proc.LastKickMessage, and that field is assigned the fully assembled kick (crux/agent/manager_kick.go:429 via recordDeliveredKickLocked), so styleSource reports what was actually delivered.
• Trust posture: the repo file is the only untrusted candidate and it is the only one scanned (kick_housestyle.go:37-47, issue-body surface, blocked → audit line + skip). For comparison, the existing AGENTS.md priming in kick_priming.go applies no ioscan at all, so this is stricter than the neighbouring repo-sourced seam, not looser. Per the PR body the "leads every kick" placement is deliberate.
• Compiles: CI skipped build because of the conflict, so I built ./pkg/housestyle ./pkg/scheduler ./pkg/dashboard ./pkg/config at ad63b34 locally — clean.

Rebase note: the four conflicting files are pkg/dashboard/server.go, status_builder.go, static/index.html and docs/api-reference.md. In server.go the collision is the gofmt realignment of the AgentStatus struct that adding StyleSource triggered — every neighbouring field line changed whitespace — so expect a mechanical, not semantic, conflict there. After the rebase, api-reference.md line citations may need bash src/scripts/check-api-reference-citations.sh --fix again.

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

[hivecommons-hive]

Read pkg/housestyle, scheduler/kick_housestyle.go, the kick_layout.go hook and the existing AGENTS.md priming path at the PR head. The logic looks correct to me; the branch is conflicting with v5 and needs the rebase the label already asks for.

What I verified:

• housestyle.Resolve (housestyle.go:108-146) never returns empty: a blocked, oversize or unreadable repo file falls through to hive inline → hive file → Builtin, and each loser is recorded in Skipped, which resolveHouseStyle turns into one house_style_skip audit line each (kick_housestyle.go:48-54). Missing files are silent (readCandidate, housestyle.go:152-156), so the common no-file case produces no audit noise.
• The repo file is located via the same agentsRepoRoot helper AGENTS.md uses (kick_priming.go:36-48), so it reads from the primary repo's checkout only. The scan runs on repo text only, with the SurfaceIssueBody policy (kick_housestyle.go:38-46); hive-supplied text is trusted. When ioscan is off the repo file applies unscanned — that is the same posture primeAgentsMd already has (kick_priming.go:81-112, no scan), so this does not widen the existing trust boundary.
• insertAfterKickHeader (kick_layout.go:142-151) places the section right after the first header line, ahead of the other static seams, which is what keeps it inside the cacheable prefix.
• Precedence repo > hive > built-in is the one #14575 specifies, so I am not raising it as a question.

One note: the PR says Fixes #14575, but #14575's proposal includes a Contents-API fallback for HIVE_STYLE.md when no checkout is wired, which this PR deliberately leaves out (docs/house-style.md:90, "Non-goals" in the body). If that part is meant to stay open as a follow-up, Refs #14575 (with the leftover named) keeps the issue from auto-closing on merge; if you consider the issue done without it, Fixes is right — your call as its author.

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

[hivecommons-hive]

@clubanderson is auto-promoted for contributor-lane merging on this PR: the last 5 merged PRs by this author in this hive's repositories have no revert or sentinel-alert evidence. CI, reviewer verdict, diff fences, soak, holds and branch protection still apply.

[hivecommons-hive]

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Failing checks:

• test (rest 2/4)
• test (rest 3/4)

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

[hivecommons-hive]

The design and the code read correctly to me; the red CI is three ratchets the diff trips, all mechanical. Nothing here needs a redesign.

What I verified in the tree (head ef7bbd0, base v5)

• src/pkg/housestyle/housestyle.go — precedence repo > inline > file > built-in is implemented as described; oversize candidates are skipped whole via readCandidate, blocked repo text falls through, and Resolve can never return empty (Builtin floor). SourceFromKick validates the parsed source against the three constants, so a kick that merely contains the header text can't inject an arbitrary value into /api/status.
• src/pkg/scheduler/kick_housestyle.go — only repo-sourced text goes through in.Scan; ioscan.SurfaceIssueBody and recordIoscanBlock are the existing seams. The helpers it leans on all exist on v5 (insertAfterKickHeader kick_layout.go:141, agentsRepoRoot kick_priming.go:36, PrimaryRepoForAgent config/agent_repos.go:158, ioscanEnabled/auditLogger ioscan_enforce.go:123,135).
• kick_layout.go:83 — the house-style seam is first in staticSeams, which (applied in reverse) puts it directly under the header. Static per agent, so the cacheable-prefix claim holds.

Why CI is red — each is caused by this diff

1. changelog-fragment-guard: changelog.d/added-house-style.md is a prose paragraph; the guard requires every fragment to start with a - bullet ("it IS the entry; the compiler owns the ### headings"). changelog.d/added-14582.md already carries a valid one-line entry — drop added-house-style.md (or fold its text into the bullet).
2. test (rest 3/4) — TestDashboardLoginNeverRequestsRepoScope: pkg/github/deviceflow_test.go:213 forbids the regex "repo" anywhere in pkg/dashboard/server.go. The new field comment at server.go:778 contains the literal "repo" (in quotes). It is a comment, not a scope request, so this is a lexical false positive against the guard — but it will keep failing until the quotes come off (e.g. `repo` or repo).
3. test (rest 2/4) — TestDashboardImportRatchet: status_builder.go:27 adds pkg/dashboard → pkg/housestyle, which is not in src/internal/testutil/dashboard_import_allowlist.txt (the PR does not touch that file). Either add it with a one-line justification, or move SourceFromKick behind an existing seam the dashboard already imports.

coverage and the aggregate test job fail only because the rest shard failed; they should clear with 2 and 3.

One mismatch between body and code, minor: the body says the hive default is "project.style inline, else project.style_file" — that is what Resolve does, but note a blank-after-trim project.style falls through to style_file while a non-blank oversize project.style records a Skip and does not try style_file (housestyle.go Resolve, the inline branch returns before the else if). Probably intended — an operator who set inline text meant inline — but worth a sentence in docs/house-style.md since the two cases behave differently.

Correctness of the feature itself looks fine to me; this is a three-line fix-up for the author.

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

[hivecommons-hive]

Read pkg/housestyle, scheduler/kick_housestyle.go, the kick_layout.go seam, and the dashboard wiring against v5. The feature logic looks correct to me (precedence, cap, ioscan refusal → fall-through, static-prefix placement). The red CI is three mechanical things, all in this diff:

1. TestDashboardImportRatchet — test (rest 2/4) (medium)
src/pkg/dashboard/status_builder.go:27 adds an import of pkg/housestyle, which is not in src/internal/testutil/dashboard_import_allowlist.txt. The ratchet fails with "pkg/dashboard gained a new dependency on pkg/housestyle … add it to the allowlist with justification in the PR". Either add the line, or have the scheduler stamp the source onto the process record so the dashboard doesn't need the package just to call SourceFromKick.

2. TestDashboardLoginNeverRequestsRepoScope — test (rest 3/4) (medium)
The new comment at src/pkg/dashboard/server.go:778 contains the literal "repo" (with quotes). src/pkg/github/deviceflow_test.go:216 greps server.go for "repo" as a #1927 scope guard and does not distinguish comments from code. Drop the quotes in the comment (repo / hive / built-in) and the test passes; nothing about the login path actually changed.

3. changelog.d/added-house-style.md is malformed and redundant (medium)
src/scripts/compile-changelog.sh:119 requires a fragment's first line to start with - (or a <!-- release: marker). This file's first line is prose ("Every kick now opens with…"), so the next tagged v5 release will abort on it — the same class of failure #14593 is currently fixing for docs-crux-stage4.md. changelog.d/added-14582.md already carries the one-line entry; I'd delete added-house-style.md outright.

One low note, not a blocker: housestyle.go:148 (} else if in.HiveFile != "") means an oversize project.style falls straight to built-in rather than trying style_file, while the StyleMaxBytes doc at config.go:969 says "the next source applies". Either behaviour is fine; the comment and code should just agree.

The coverage failure is downstream of the rest shards and should clear with the above.

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

[hivecommons-hive]

Read at 6137ba4 against the tree. The precedence logic and the untrusted-repo handling do what the body says; no defects found.

Verified

• housestyle.Resolve (src/pkg/housestyle/housestyle.go:108–141): repo file → hive inline → hive file → built-in, each candidate skipped whole on oversize or scanner block with a Skip recorded, never truncated. Oversize inline project.style falls to built-in without trying style_file — consistent with the documented "inline, else file".
• Scanner runs on repo text only (housestyle.go:116; scheduler/kick_housestyle.go:40 uses SurfaceIssueBody), and the skip path writes the house_style_skip audit line per candidate as claimed.
• insertAfterKickHeader (kick_layout.go:142–151) puts the section directly under the first line, and the layout wiring at kick_layout.go:83 keeps it inside the static prefix.
• SourceFromKick only accepts the three known source names, so a repo file containing the header string cannot spoof the dashboard field (the real header always precedes it).

Open question (info, not a defect) — readCandidate uses os.ReadFile (housestyle.go:149), which follows symlinks, so a repo could point HIVE_STYLE.md at a host file and have up to style_max_bytes of it land in every kick. This is the same posture AGENTS.md already has (src/crux/agentsmd/agentsmd.go:203), so it is not a regression; noting it because this PR adds a second repo-controlled → prompt channel. An os.Lstat + ModeSymlink refusal would close it cheaply if the owner wants that.

Not approving (human signature), but I see nothing blocking.

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

[hivecommons-hive]

Read pkg/housestyle/housestyle.go, pkg/scheduler/kick_housestyle.go, the assembleKick seam list, and the AGENTS.md priming path it sits beside. The precedence, cap and fall-through logic match the description: Resolve (housestyle.go:113-150) skips an oversize or scanner-blocked repo candidate whole and falls to inline → file → Builtin, never clipping; readCandidate (housestyle.go:155-171) is silent only on ErrNotExist, so unreadable files do surface as skips. addHouseStyle is the first entry in staticSeams (kick_layout.go:83) and the seams are applied in reverse, so it does land directly under the kick header, which is also why SourceFromKick's first-match strings.Index (housestyle.go:183) cannot be spoofed by a later issue body containing the same header text. The scan hook uses the real ioscan.ScanInputFrom(..., SurfaceIssueBody, policy) API (ioscan/policy.go:179). Looks correct to me.

One low-severity note on the trust boundary the PR itself draws:

• housestyle.go:156 — os.ReadFile(RepoRoot/HIVE_STYLE.md) follows symlinks, so the "untrusted" repo file can point outside the checkout. A HIVE_STYLE.md -> ../../some/host/file committed to the managed repo makes the scheduler (not the agent) read up to style_max_bytes of any file it can see and place it at the top of every kick. ioscan at the issue-body policy will catch credential-shaped text, but not arbitrary host content. This is parity with the existing AGENTS.md read (crux/agentsmd/agentsmd.go:203, also plain os.ReadFile, and that one is not scanned at all), so it is not a regression — but since this PR is the one declaring the file untrusted and adding a scan, an os.Lstat + "refuse symlink / refuse non-regular file" check in readCandidate for SourceRepo would close it cheaply and give the audit line a clear reason. Suggestion, not a blocker.

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

[hivecommons-hive]

Evidence bundle `#145826137ba4` sha256:749db62b4ee53e750e23c6f49421e2f9a9c8b4cff361ff2d875ee5f0fd9c1353 — download from the dashboard or `hivectl review evidence #14582`.

[hivecommons-hive]

merged by Hive trusted-author auto-merge: author @clubanderson holds role owner and GitHub permission admin on repo; CI green at 6137ba4.

[github-actions]

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback