From bfad8b25d3fb5fb3362bf7893cff881f200df3d4 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 18 Nov 2026 00:31:09 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=90=9B=20needs-sha:=20exempt=20owner/?= =?UTF-8?q?detailed=20issues,=20add=20an=20overrideable=20waiver,=20show?= =?UTF-8?q?=20the=20hold=20on=20the=20row=20(#18866)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The SHA-hold sweep no longer gates the hive's own accounts, owners/maintainers or issues whose body names concrete repo file paths (self-attested, documented), and lifts a needs-sha already applied to them. A persistent sha-waived label (row menu Waive/Restore SHA requirement, gated like hold release) overrides the gate and is never re-added. Held issues show a pill and Open-chevron note via the new sha_hold stage-tracker field. Signed-off-by: Andrew Anderson Co-authored-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- .../fixed-18866-needs-sha-exempt-visible.md | 1 + dashboard/openapi.json | 114 ++++++++++ src/docs/api-reference/agents-and-controls.md | 18 +- src/docs/api-reference/auth.md | 8 +- src/docs/api-reference/beads.md | 10 +- src/docs/api-reference/configuration.md | 36 ++-- src/docs/api-reference/dashboard-misc.md | 24 +-- src/docs/api-reference/inception.md | 28 +-- src/docs/api-reference/knowledge.md | 92 ++++---- src/docs/api-reference/nous.md | 50 ++--- src/docs/api-reference/packs-and-acmm.md | 27 +-- .../dashboard-sections/activity-monitor.md | 4 + .../glossary-and-operations.md | 2 +- .../labels-and-control-signals/reference.md | 30 ++- src/docs/notifications.md | 1 + src/docs/operator-reference/README.md | 2 +- src/hive.yaml.example | 3 +- src/pkg/config/issues.go | 11 +- src/pkg/dashboard/api.go | 1 + src/pkg/dashboard/api_repo_item_sha_waiver.go | 203 ++++++++++++++++++ src/pkg/dashboard/stage_tracker.go | 4 + src/pkg/dashboard/stage_tracker_build.go | 1 + src/pkg/dashboard/stage_tracker_sha_hold.go | 76 +++++++ .../dashboard/stage_tracker_sha_hold_test.go | 186 ++++++++++++++++ src/pkg/dashboard/static-src/css/tracker.css | 2 + .../static-src/js/tracker-actions.js | 15 +- .../static-src/js/tracker-row-strip.js | 31 ++- src/pkg/dashboard/static/index.html | 48 ++++- src/pkg/github/client.go | 61 +++++- src/pkg/github/notification_write_sites.go | 1 + src/pkg/github/sha_hold_exempt.go | 188 ++++++++++++++++ src/pkg/github/sha_hold_exempt_test.go | 180 ++++++++++++++++ src/pkg/github/sha_hold_soft_test.go | 19 +- 33 files changed, 1293 insertions(+), 184 deletions(-) create mode 100644 changelog.d/fixed-18866-needs-sha-exempt-visible.md create mode 100644 src/pkg/dashboard/api_repo_item_sha_waiver.go create mode 100644 src/pkg/dashboard/stage_tracker_sha_hold.go create mode 100644 src/pkg/dashboard/stage_tracker_sha_hold_test.go create mode 100644 src/pkg/github/sha_hold_exempt.go create mode 100644 src/pkg/github/sha_hold_exempt_test.go diff --git a/changelog.d/fixed-18866-needs-sha-exempt-visible.md b/changelog.d/fixed-18866-needs-sha-exempt-visible.md new file mode 100644 index 0000000000..86a78399d2 --- /dev/null +++ b/changelog.d/fixed-18866-needs-sha-exempt-visible.md @@ -0,0 +1 @@ +- The SHA-hold gate no longer holds issues it was not meant for, and a hold is now visible and overrideable (#18866). The sweep skips issues filed by the hive's own accounts or by owners and maintainers (`project.issue_filter.reporter_trust.trusted_associations`) and issues whose body names a concrete repo file path such as `src/pkg/github/client.go` (self-attested: the path is never checked to exist, so a reporter can write one to skip the gate), and lifts a `needs-sha` already on an issue that qualifies, so an owner-filed, detailed bug like #18740 is released on the next sweep; outside reporters with no SHA and no path are still held. A maintainer can waive the requirement per issue with the persistent `sha-waived` label (row menu *Waive SHA requirement* / *Restore SHA requirement*, gated like releasing a `hold`); the sweep never re-adds `needs-sha` while it is on. Held issues show the pill *Held: needs commit SHA* and a note on the Open chevron saying how to lift it, and the waived state reads *SHA waived by *; `GET /api/stage-tracker` rows carry the new `sha_hold` field. Recording the default-branch head at filing time was left out: it would be a guess about the reporter's build, not evidence of it. diff --git a/dashboard/openapi.json b/dashboard/openapi.json index c8a753cccc..3bf17f3413 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -36373,6 +36373,120 @@ } } }, + "/api/repos/{owner}/{repo}/items/{number}/sha-waiver": { + "post": { + "tags": [ + "Status" + ], + "summary": "Waive or restore the SHA-hold requirement on one issue", + "description": "Backs the activity monitor's row menu Waive SHA requirement / Restore SHA requirement entries on an issue held by the SHA-hold gate (needs-sha). Waiving adds the persistent sha-waived label (created if missing), removes needs-sha at once and posts one App-authored comment with a hive:sha-waived marker naming the dashboard user; the SHA sweep never re-adds needs-sha while sha-waived is on. Restoring removes sha-waived and the next sweep holds the issue again if it still has no SHA and no exemption. A repeat is a no-op; pull requests have no SHA requirement (404). Same authorisation as the hold toggle; every write is audited as repo_item_sha_waiver under the dashboard user.", + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "number", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "Waived or restored (or already so)", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ok": { + "type": "boolean" + }, + "repo": { + "type": "string" + }, + "number": { + "type": "integer" + }, + "waived": { + "type": "boolean" + }, + "added": { + "type": "array", + "items": { + "type": "string" + } + }, + "removed": { + "type": "array", + "items": { + "type": "string" + } + }, + "minStatusSeq": { + "type": "integer", + "description": "Status sequence the caller should wait for before trusting /api/status again" + } + } + } + } + } + }, + "400": { + "description": "Invalid repository item" + }, + "401": { + "description": "GitHub user session required" + }, + "403": { + "description": "Write permission required" + }, + "404": { + "description": "Not an issue (pull request) or unknown item" + }, + "502": { + "description": "GitHub API error" + }, + "503": { + "description": "GitHub client not configured" + } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "waived": { + "type": "boolean", + "description": "true waives the requirement, false restores it" + } + }, + "required": [ + "waived" + ] + } + } + } + } + } + }, "/api/repos/pauses": { "get": { "tags": [ diff --git a/src/docs/api-reference/agents-and-controls.md b/src/docs/api-reference/agents-and-controls.md index bb94c2e63f..58f4b8edec 100644 --- a/src/docs/api-reference/agents-and-controls.md +++ b/src/docs/api-reference/agents-and-controls.md @@ -24,16 +24,16 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/model-advisor` | Dashboard auth/session | Model Advisor | `pkg/dashboard/api.go:156` | | `GET` | `/api/governor/pr-models` | Dashboard auth/session | Agent-authored PR distribution by normalized attribution model/backend for `window=7d`, `30d`, or `all`, including per-model rework stats, Wilson 95% `*_ci` intervals on the rates (omitted when the denominator is 0), a `coverage` block (closed-PR lookback and run-log partiality, as on `/api/contribute/effective-models`), `earliest_pr_created_at`, the top 10 most-reworked PRs, and per-bucket `hive_cost` (`usd`, `launches`, `prs_with_cost`, `usd_per_merged_pr`: the hive's estimated review/fix spend on that model's PRs from the cached `/api/launch-cost` snapshot; `usd` is `null`, not `0`, when nothing was attributed; omitted while the snapshot is not ready) with a top-level `hive_cost_coverage` (`ready`, `window_hours`, `unattributed_usd`, `backend_unsupported_usd`, `disclaimer`). Optional `model=` (matched after `modelfamily.Canonical`, so raw spellings such as `anthropic/claude-opus-5-5` work) adds `prs[]`: every PR in the window in that model's bucket, with the `most_reworked` fields plus `outcome` (`merged` / `closed_unmerged` / `open`), `agent`, `created_at`, `merged_at` and `first_pass`, sorted by review rounds + fix attempts then newest, capped at 200 with `prs_truncated: true` past that. An unknown model returns `prs: []`; without `model` the response is unchanged | `pkg/dashboard/api.go:157` | | `GET` | `/api/reviewer/accuracy` | Dashboard auth/session | Reviewer verdict calibration for the configured window: false-approve/false-block rates and confidence buckets per perspective and reviewer model | `pkg/dashboard/api.go:220` | -| `GET` | `/api/review/queue` | Dashboard auth/session | PR review queue: every open PR (agent and contributor, actionable and held) ranked by triage class, confidence band, CI state and age, with per-PR `reasons`; unreviewed items carry `pending_since` and `redispatch_count` from the review dispatch state; each entry carries `stage` `{stage, entered_at, last_activity_at, quiet_for, stalled, waiting_on_hive, past_dwell, history[]}` from the stage-label store (`stalled`/`past_dwell` follow `governor.labels.stage.dwell` and `stalled.require_quiet`; `history[]` is `{from, to, at, reason, regressed}`, newest last, capped at 8) and the top-level `hive_held` counts PRs past their stage dwell while waiting on the hive (`waiting_on_hive` and `past_dwell` both true); paged with `limit` (1-200, default 50) and `offset` | `pkg/dashboard/api.go:503` | -| `POST` | `/api/review/queue/{owner}/{repo}/{number}/superseded/close` | Owner only | Close a superseded PR now (grace window or not): posts the close comment, adds `hive/superseded`, closes it | `pkg/dashboard/api.go:506` | -| `POST` | `/api/review/queue/{owner}/{repo}/{number}/superseded/keep-open` | Owner only | Keep a superseded PR open: adds `hive/keep-open`, which the supersession sweep never auto-closes | `pkg/dashboard/api.go:507` | -| `GET` | `/api/review/pipeline` | Dashboard auth/session | Review pipeline: one card per review-queue PR placed in its stage (`unreviewed`, `reviewing`, `changes_requested`, `fixing`, `human_hold`, `approved`, `merged`, `abandoned`) with `since`, `reviewers`, P0–P3 `severity` counts, `loop_count`/`loop_cap`, `next_action` and `reasons`; filtered by `repo` and `stage`, paged with `limit` (1-200, default 50) and `offset` | `pkg/dashboard/api.go:511` | +| `GET` | `/api/review/queue` | Dashboard auth/session | PR review queue: every open PR (agent and contributor, actionable and held) ranked by triage class, confidence band, CI state and age, with per-PR `reasons`; unreviewed items carry `pending_since` and `redispatch_count` from the review dispatch state; each entry carries `stage` `{stage, entered_at, last_activity_at, quiet_for, stalled, waiting_on_hive, past_dwell, history[]}` from the stage-label store (`stalled`/`past_dwell` follow `governor.labels.stage.dwell` and `stalled.require_quiet`; `history[]` is `{from, to, at, reason, regressed}`, newest last, capped at 8) and the top-level `hive_held` counts PRs past their stage dwell while waiting on the hive (`waiting_on_hive` and `past_dwell` both true); paged with `limit` (1-200, default 50) and `offset` | `pkg/dashboard/api.go:504` | +| `POST` | `/api/review/queue/{owner}/{repo}/{number}/superseded/close` | Owner only | Close a superseded PR now (grace window or not): posts the close comment, adds `hive/superseded`, closes it | `pkg/dashboard/api.go:507` | +| `POST` | `/api/review/queue/{owner}/{repo}/{number}/superseded/keep-open` | Owner only | Keep a superseded PR open: adds `hive/keep-open`, which the supersession sweep never auto-closes | `pkg/dashboard/api.go:508` | +| `GET` | `/api/review/pipeline` | Dashboard auth/session | Review pipeline: one card per review-queue PR placed in its stage (`unreviewed`, `reviewing`, `changes_requested`, `fixing`, `human_hold`, `approved`, `merged`, `abandoned`) with `since`, `reviewers`, P0–P3 `severity` counts, `loop_count`/`loop_cap`, `next_action` and `reasons`; filtered by `repo` and `stage`, paged with `limit` (1-200, default 50) and `offset` | `pkg/dashboard/api.go:512` | | `GET` | `/api/review/dispatch/events` | Dashboard auth/session | Webhook review dispatch queue: `enabled`, `webhooks_configured`, `debounce_s`, `pending` (soonest first) and `recent` (newest first) dispatches with repo, number, head SHA, action, timestamps and coalesced count, plus `stats` counters; in memory, never calls GitHub | `pkg/dashboard/api_review_event_dispatch.go:15` | -| `GET` | `/api/review/evidence` | Merger or owner | [Review evidence bundle](../review-evidence.md) for one PR head. Query `repo` (`owner/name`), `number`, optional `head` (full SHA or unique prefix of at least 7 characters; `409` when ambiguous; default is the newest head), `format=json\|zip` (default `json`) and `download=1` for an attachment. `json` returns the bundle bytes exactly as sealed (verdicts, posted reviews, policy, CI check runs, sentinel findings, human actions, merge event, `hash`, optional `signature`); `zip` adds `verdicts.json`, `review-links.json` and a `manifest.json` of SHA-256s plus the signing public key when readable. `400` for a bad `repo`/`number`; `404` with `status: "expired"`/`expired: true` when retention removed a bundle Hive can prove existed, otherwise `status: "not_found"` | `pkg/dashboard/api.go:515` | -| `GET` | `/api/review/evidence/list` | Merger or owner | Every retained evidence bundle id and head for one PR (`repo`, `number`), oldest first, with the newest marked latest; `400` for a bad `repo`/`number` | `pkg/dashboard/api.go:516` | -| `GET` | `/api/evidence/write-counters` | Merger or owner | Durable attempted vs blocked agent GitHub write counters ([#12069](https://github.com/hivecommons/hive/issues/12069)): `totals` by intent tier (ACMM mode) with `blocked_by_reason`, and `weeks` keyed by the UTC Monday of each ISO week with per-tier and per-reason counts. Persisted across restarts; observation only, never gates a write or merge. Empty `totals`/`weeks` before anything is recorded | `pkg/dashboard/api.go:518` | -| `GET` | `/api/evidence/summary` | Dashboard auth/session | Read-only aggregate over `/data/evidence` bundles (schema v1) plus reviewer accuracy. Query `hours` (default 24, capped like `/api/pr-throughput`; `0` = all time) or a custom `from`/`to` range (RFC3339 or `YYYY-MM-DD`, date-only `to` inclusive, `to` defaults to now; `400` when `to` precedes `from`, the span exceeds 3 × 366 days, or `to` is given without `from`; the response echoes `from`/`to`), `repo` (`owner/name`) and `author_kind=human\|agent\|bot`; `400` for a bad value. A PR falls in the window by its open time (earliest bundle `created_at` or `merge.opened_at`), never by when a bundle was written; all bundles of a PR are folded so the newest supplies verdicts and the merge / `reverted_by` / backfilled close come from whichever record knows them. Returns `available_windows` (`{"24","168","720","all"}` → PR count under the same filters), `outcomes_by_author_kind` (merged/closed/open; `closed` comes from backfilled records, `reverted_14d` is null until bundles record it), `outcomes_by_author_family` and `outcomes_by_author_model` (the same outcome fields keyed by the author's model family and by canonical author model, `human` / `unknown` when no model was recorded; [#18720](https://github.com/hivecommons/hive/issues/18720)), `reviewer_calibration` buckets per perspective, `reviewer_accuracy_by_model` split by author kind (blocks split into `enforced_blocks` / `advisory_blocks` by `policy.require_approval`; advisory blocks that preceded a merge are `dissent_before_merge`, not false blocks), `sentinel_hits_per_week`, `shadow_gate` (`n`, `would_have_held`, `would_have_blocked`, and per gate `review_gate` / `intent` the evaluated `n` with `held` / `passed` outcomes `{n, merged, closed, open, reverted}`, plus `review_gate_by_lane` `{merge_eligible, self_merge}`), `write_counters` (per intent tier `{attempted, blocked, blocked_by_reason}` from the proxy write counter file; omitted when absent or unreadable), `write_activity` (blocked ÷ every agent write in the window: `total_writes`, `blocked`, `direct` `{recorded, since, partial_coverage, attempted, blocked, by_tier, blocked_by_reason}` from the proxy's weekly counter buckets under `/data/hive-metrics/write-counters.json`, `mediated` `{n, refused, by_action}` from the audit log), `claim_vs_verdict` (per ISO week of agent-authored PRs: `n`, `claimed`, `ci_captured`, `ci_not_green`, `verdict_not_approve`, `both`; records with empty CI are excluded from the CI column and disclosed under `missing.records_empty_ci`), `ci_recovery` (`policy` `{self_authored_automerge, required_checks}`, `n`, `at_claim` `{green, red, pending, none}`, `red` `{n, recovered_merged, green_open, abandoned, pending, outcome_unknown, enriched, not_enriched, median_pushes_to_green, median_hours_to_green, same_head_recovered}`, `gate` `{merged_n, with_checks, green, green_from_bundles, non_required_red, required_unknown, breaches, breach_prs[], suspected, suspected_prs[], pending, unknown, green_to_merge_n, median_green_to_merge_hours}` over every merged PR by GitHub-confirmed state of the *required* checks on the merged head, as the merge gate judges (`breach_prs[]` carry `red`, `merged_by`; a red non-required check is disclosed, not a breach; a red review-time snapshot, a required check with no run, or a red read without a resolvable required set is only suspected), and `convergence` `{n, passes {"1","2","3","4+","never"}, settled, in_flight, unknown, median_passes, from_github, from_bundles, by_week[]}` over agent PRs by CI passes to first green, from the durable `/data/hive-metrics/ci-recovery.json` GitHub check-run trail rollup), `work_balance` (per ISO week: `n`, `opened` by actor kind `{human, agent, bot}`, `closed`, `prs_opened`, `prs_merged`, `prs_closed`, `queue_issues`, `queue_prs`, `issue_source` `github|audit`, `throttled`) with `work_balance_sources` (`issues_github_since`, `issues_fetched_at`, `issues_known`, `audit_only_weeks`, `issue_series_weeks`, `queue_samples`, `queue_retention_days`; issues from the durable GitHub rollup `/data/hive-metrics/issue-activity.json` for weeks at or after `issues_github_since` and, for earlier weeks, from the backfilled issue series `///issues/.json` written by the issue backfill ([#12527](https://github.com/hivecommons/hive/pull/12527)) when its coverage spans the requested portion of the week (`issue_series_weeks` counts the repo-weeks it supplied), else the audit log (`audit_only_weeks`), PRs from folded bundles, queue depth from governor snapshots; `missing.issues_human_opens_unobserved` is true while no GitHub rollup exists unless the issue series covers every row, and whenever any row fell back to the audit log, `missing.throttle_windows_unavailable` discloses that no governor throttle windows are reported), `intent_counters` (per intent tier `{attempted, blocked}` from `/data/hive-metrics/intent-counters.json` — evaluations and the subset the intent gate would have blocked with enforcement on, [#12362](https://github.com/hivecommons/hive/issues/12362); omitted when absent or unreadable), `complexity_by_repo` (per managed repo the newest 12 monthly complexity snapshots, oldest first, each `{month, ref, captured_at, files, functions, mean_cyclomatic, median_cyclomatic, p90_cyclomatic, max_cyclomatic, functions_over_threshold, threshold, static_warnings, static_warnings_by_tool}`; omitted when no repo has a snapshot), the `/api/reviewer/accuracy` summary, and `n` plus `missing` counts (unknown-model verdicts, empty CI, unreadable records). Never consulted by merge decisions. | `pkg/dashboard/api.go:521` | -| `GET` | `/api/benchmarks/export` | Owner only | Anonymized per-PR [benchmark records](../benchmarks.md) (schema `hivecommons/benchmarks` `result.schema.json`) built from the evidence bundles updated since `since` (RFC3339 or `YYYY-MM-DD`; default 90 days; `400` when malformed) plus `hive_hash`, `publish`, `generated_at` and `count`. `records` is empty when `benchmarks.publish: false`; repo/org names appear only for GitHub-public repos when `benchmarks.repo_consent` is on | `pkg/dashboard/api.go:522` | +| `GET` | `/api/review/evidence` | Merger or owner | [Review evidence bundle](../review-evidence.md) for one PR head. Query `repo` (`owner/name`), `number`, optional `head` (full SHA or unique prefix of at least 7 characters; `409` when ambiguous; default is the newest head), `format=json\|zip` (default `json`) and `download=1` for an attachment. `json` returns the bundle bytes exactly as sealed (verdicts, posted reviews, policy, CI check runs, sentinel findings, human actions, merge event, `hash`, optional `signature`); `zip` adds `verdicts.json`, `review-links.json` and a `manifest.json` of SHA-256s plus the signing public key when readable. `400` for a bad `repo`/`number`; `404` with `status: "expired"`/`expired: true` when retention removed a bundle Hive can prove existed, otherwise `status: "not_found"` | `pkg/dashboard/api.go:516` | +| `GET` | `/api/review/evidence/list` | Merger or owner | Every retained evidence bundle id and head for one PR (`repo`, `number`), oldest first, with the newest marked latest; `400` for a bad `repo`/`number` | `pkg/dashboard/api.go:517` | +| `GET` | `/api/evidence/write-counters` | Merger or owner | Durable attempted vs blocked agent GitHub write counters ([#12069](https://github.com/hivecommons/hive/issues/12069)): `totals` by intent tier (ACMM mode) with `blocked_by_reason`, and `weeks` keyed by the UTC Monday of each ISO week with per-tier and per-reason counts. Persisted across restarts; observation only, never gates a write or merge. Empty `totals`/`weeks` before anything is recorded | `pkg/dashboard/api.go:519` | +| `GET` | `/api/evidence/summary` | Dashboard auth/session | Read-only aggregate over `/data/evidence` bundles (schema v1) plus reviewer accuracy. Query `hours` (default 24, capped like `/api/pr-throughput`; `0` = all time) or a custom `from`/`to` range (RFC3339 or `YYYY-MM-DD`, date-only `to` inclusive, `to` defaults to now; `400` when `to` precedes `from`, the span exceeds 3 × 366 days, or `to` is given without `from`; the response echoes `from`/`to`), `repo` (`owner/name`) and `author_kind=human\|agent\|bot`; `400` for a bad value. A PR falls in the window by its open time (earliest bundle `created_at` or `merge.opened_at`), never by when a bundle was written; all bundles of a PR are folded so the newest supplies verdicts and the merge / `reverted_by` / backfilled close come from whichever record knows them. Returns `available_windows` (`{"24","168","720","all"}` → PR count under the same filters), `outcomes_by_author_kind` (merged/closed/open; `closed` comes from backfilled records, `reverted_14d` is null until bundles record it), `outcomes_by_author_family` and `outcomes_by_author_model` (the same outcome fields keyed by the author's model family and by canonical author model, `human` / `unknown` when no model was recorded; [#18720](https://github.com/hivecommons/hive/issues/18720)), `reviewer_calibration` buckets per perspective, `reviewer_accuracy_by_model` split by author kind (blocks split into `enforced_blocks` / `advisory_blocks` by `policy.require_approval`; advisory blocks that preceded a merge are `dissent_before_merge`, not false blocks), `sentinel_hits_per_week`, `shadow_gate` (`n`, `would_have_held`, `would_have_blocked`, and per gate `review_gate` / `intent` the evaluated `n` with `held` / `passed` outcomes `{n, merged, closed, open, reverted}`, plus `review_gate_by_lane` `{merge_eligible, self_merge}`), `write_counters` (per intent tier `{attempted, blocked, blocked_by_reason}` from the proxy write counter file; omitted when absent or unreadable), `write_activity` (blocked ÷ every agent write in the window: `total_writes`, `blocked`, `direct` `{recorded, since, partial_coverage, attempted, blocked, by_tier, blocked_by_reason}` from the proxy's weekly counter buckets under `/data/hive-metrics/write-counters.json`, `mediated` `{n, refused, by_action}` from the audit log), `claim_vs_verdict` (per ISO week of agent-authored PRs: `n`, `claimed`, `ci_captured`, `ci_not_green`, `verdict_not_approve`, `both`; records with empty CI are excluded from the CI column and disclosed under `missing.records_empty_ci`), `ci_recovery` (`policy` `{self_authored_automerge, required_checks}`, `n`, `at_claim` `{green, red, pending, none}`, `red` `{n, recovered_merged, green_open, abandoned, pending, outcome_unknown, enriched, not_enriched, median_pushes_to_green, median_hours_to_green, same_head_recovered}`, `gate` `{merged_n, with_checks, green, green_from_bundles, non_required_red, required_unknown, breaches, breach_prs[], suspected, suspected_prs[], pending, unknown, green_to_merge_n, median_green_to_merge_hours}` over every merged PR by GitHub-confirmed state of the *required* checks on the merged head, as the merge gate judges (`breach_prs[]` carry `red`, `merged_by`; a red non-required check is disclosed, not a breach; a red review-time snapshot, a required check with no run, or a red read without a resolvable required set is only suspected), and `convergence` `{n, passes {"1","2","3","4+","never"}, settled, in_flight, unknown, median_passes, from_github, from_bundles, by_week[]}` over agent PRs by CI passes to first green, from the durable `/data/hive-metrics/ci-recovery.json` GitHub check-run trail rollup), `work_balance` (per ISO week: `n`, `opened` by actor kind `{human, agent, bot}`, `closed`, `prs_opened`, `prs_merged`, `prs_closed`, `queue_issues`, `queue_prs`, `issue_source` `github|audit`, `throttled`) with `work_balance_sources` (`issues_github_since`, `issues_fetched_at`, `issues_known`, `audit_only_weeks`, `issue_series_weeks`, `queue_samples`, `queue_retention_days`; issues from the durable GitHub rollup `/data/hive-metrics/issue-activity.json` for weeks at or after `issues_github_since` and, for earlier weeks, from the backfilled issue series `///issues/.json` written by the issue backfill ([#12527](https://github.com/hivecommons/hive/pull/12527)) when its coverage spans the requested portion of the week (`issue_series_weeks` counts the repo-weeks it supplied), else the audit log (`audit_only_weeks`), PRs from folded bundles, queue depth from governor snapshots; `missing.issues_human_opens_unobserved` is true while no GitHub rollup exists unless the issue series covers every row, and whenever any row fell back to the audit log, `missing.throttle_windows_unavailable` discloses that no governor throttle windows are reported), `intent_counters` (per intent tier `{attempted, blocked}` from `/data/hive-metrics/intent-counters.json` — evaluations and the subset the intent gate would have blocked with enforcement on, [#12362](https://github.com/hivecommons/hive/issues/12362); omitted when absent or unreadable), `complexity_by_repo` (per managed repo the newest 12 monthly complexity snapshots, oldest first, each `{month, ref, captured_at, files, functions, mean_cyclomatic, median_cyclomatic, p90_cyclomatic, max_cyclomatic, functions_over_threshold, threshold, static_warnings, static_warnings_by_tool}`; omitted when no repo has a snapshot), the `/api/reviewer/accuracy` summary, and `n` plus `missing` counts (unknown-model verdicts, empty CI, unreadable records). Never consulted by merge decisions. | `pkg/dashboard/api.go:522` | +| `GET` | `/api/benchmarks/export` | Owner only | Anonymized per-PR [benchmark records](../benchmarks.md) (schema `hivecommons/benchmarks` `result.schema.json`) built from the evidence bundles updated since `since` (RFC3339 or `YYYY-MM-DD`; default 90 days; `400` when malformed) plus `hive_hash`, `publish`, `generated_at` and `count`. `records` is empty when `benchmarks.publish: false`; repo/org names appear only for GitHub-public repos when `benchmarks.repo_consent` is on | `pkg/dashboard/api.go:523` | | `GET` | `/api/agents` | Dashboard auth/session | Agents List | `pkg/dashboard/api.go:305` | | `POST` | `/api/agents` | Owner only | Agent Create | `pkg/dashboard/api.go:306` | | `POST` | `/api/agents/import` | Owner only | Agent Import | `pkg/dashboard/api.go:307` | diff --git a/src/docs/api-reference/auth.md b/src/docs/api-reference/auth.md index 86bcd20728..767552f308 100644 --- a/src/docs/api-reference/auth.md +++ b/src/docs/api-reference/auth.md @@ -27,7 +27,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1805` | | `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1806` | | `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1807` | -| `GET` | `/api/github-owner-identity` | Owner only | The hive owner's GitHub identity for remote repos ([#18197](https://github.com/hivecommons/hive/issues/18197)): `connected`, `login`, `scope`, `connected_at`, `usable`, `reason`, `verified_at`, `scope_required` (`public_repo`), `private_repos_supported` (false) and `file` (the token file path on the spoke). Never the token | `pkg/dashboard/api.go:562` | -| `POST` | `/api/github-owner-identity/start` | Owner only | Start the consent: a GitHub device flow with the spoke's `oauth_client_id` asking for `public_repo`, separate from the scope-free login flow. Returns `user_code`, `verification_uri`, `expires_in`, `interval`, `scope` and the `flow_id` the poll must present. 502 when GitHub refused the device-code request | `pkg/dashboard/api.go:563` | -| `POST` | `/api/github-owner-identity/poll` | Owner only | Poll the consent with `{"flow_id"}`: `status` `pending` / `slow_down` (poll again), `complete` (with `login` and the identity) or `error`. On completion the granted scope must cover `public_repo`, the token must validate and the account must be the logged-in owner's; the identity is then stored on the spoke (`/data/secrets/github-owner-token`, `HIVE_GITHUB_OWNER_TOKEN_FILE` overrides) and the reference-repo policies re-resolve. 400 without a live flow or with the wrong `flow_id`; audited as `github_owner_identity_connected` / `_rejected` | `pkg/dashboard/api.go:564` | -| `DELETE` | `/api/github-owner-identity` | Owner only | Disconnect: removes the token file, drops every write-tier reference repo to read-only on the next pass, returns the previous `login` and a `note` that GitHub-side revocation is done under Settings → Applications on github.com; audited as `github_owner_identity_disconnected` | `pkg/dashboard/api.go:565` | +| `GET` | `/api/github-owner-identity` | Owner only | The hive owner's GitHub identity for remote repos ([#18197](https://github.com/hivecommons/hive/issues/18197)): `connected`, `login`, `scope`, `connected_at`, `usable`, `reason`, `verified_at`, `scope_required` (`public_repo`), `private_repos_supported` (false) and `file` (the token file path on the spoke). Never the token | `pkg/dashboard/api.go:563` | +| `POST` | `/api/github-owner-identity/start` | Owner only | Start the consent: a GitHub device flow with the spoke's `oauth_client_id` asking for `public_repo`, separate from the scope-free login flow. Returns `user_code`, `verification_uri`, `expires_in`, `interval`, `scope` and the `flow_id` the poll must present. 502 when GitHub refused the device-code request | `pkg/dashboard/api.go:564` | +| `POST` | `/api/github-owner-identity/poll` | Owner only | Poll the consent with `{"flow_id"}`: `status` `pending` / `slow_down` (poll again), `complete` (with `login` and the identity) or `error`. On completion the granted scope must cover `public_repo`, the token must validate and the account must be the logged-in owner's; the identity is then stored on the spoke (`/data/secrets/github-owner-token`, `HIVE_GITHUB_OWNER_TOKEN_FILE` overrides) and the reference-repo policies re-resolve. 400 without a live flow or with the wrong `flow_id`; audited as `github_owner_identity_connected` / `_rejected` | `pkg/dashboard/api.go:565` | +| `DELETE` | `/api/github-owner-identity` | Owner only | Disconnect: removes the token file, drops every write-tier reference repo to read-only on the next pass, returns the previous `login` and a `note` that GitHub-side revocation is done under Settings → Applications on github.com; audited as `github_owner_identity_disconnected` | `pkg/dashboard/api.go:566` | diff --git a/src/docs/api-reference/beads.md b/src/docs/api-reference/beads.md index 500bb77a6b..2206cbf9da 100644 --- a/src/docs/api-reference/beads.md +++ b/src/docs/api-reference/beads.md @@ -5,8 +5,8 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| -| `GET` | `/api/beads` | Dashboard auth/session | Beads List | `pkg/dashboard/api.go:487` | -| `GET` | `/api/beads/{agent}` | Dashboard auth/session | Beads List | `pkg/dashboard/api.go:488` | -| `POST` | `/api/beads/{agent}` | Owner only | Beads Create | `pkg/dashboard/api.go:489` | -| `POST` | `/api/beads/reset` | Owner only | Beads Reset | `pkg/dashboard/api.go:490` | -| `POST` | `/api/beads/reset/{agent}` | Owner only | Beads Reset Agent | `pkg/dashboard/api.go:491` | +| `GET` | `/api/beads` | Dashboard auth/session | Beads List | `pkg/dashboard/api.go:488` | +| `GET` | `/api/beads/{agent}` | Dashboard auth/session | Beads List | `pkg/dashboard/api.go:489` | +| `POST` | `/api/beads/{agent}` | Owner only | Beads Create | `pkg/dashboard/api.go:490` | +| `POST` | `/api/beads/reset` | Owner only | Beads Reset | `pkg/dashboard/api.go:491` | +| `POST` | `/api/beads/reset/{agent}` | Owner only | Beads Reset Agent | `pkg/dashboard/api.go:492` | diff --git a/src/docs/api-reference/configuration.md b/src/docs/api-reference/configuration.md index 67169db1f3..989338fb38 100644 --- a/src/docs/api-reference/configuration.md +++ b/src/docs/api-reference/configuration.md @@ -80,17 +80,17 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/config/github/webhooks` | Owner only | Config GitHub Webhooks (payload URL, events, secret source, receiver health, App hook permissions) | `pkg/dashboard/api_github_webhook_setup.go:88` | | `POST` | `/api/config/github/webhooks/secret` | Owner only | Config GitHub Webhooks Generate Secret (returned once) | `pkg/dashboard/api_github_webhook_setup.go:89` | | `POST` | `/api/config/github/webhooks/create` | Owner only | Config GitHub Webhooks Create Hook (through the App installation) | `pkg/dashboard/api_github_webhook_setup.go:90` | -| `GET` | `/api/config/sidebar` | Dashboard auth/session | Sidebar Get | `pkg/dashboard/api.go:358` | -| `PUT` | `/api/config/sidebar` | Dashboard auth/session | Sidebar Set | `pkg/dashboard/api.go:359` | -| `GET` | `/api/config/backends` | Dashboard auth/session | Backends | `pkg/dashboard/api.go:360` | -| `GET` | `/api/compliance/status` | Merger or owner | Evaluated compliance controls for the frameworks in `compliance.frameworks` (`compliance.Report`, JSON): per control `meets`/`deviates`/`off`/`not_covered` with current vs recommended value per mapped setting, a summary, and the non-certification disclaimer — see [Compliance](../compliance.md) ([#11078](https://github.com/hivecommons/hive/issues/11078)) | `pkg/dashboard/api.go:350` | -| `GET` | `/api/compliance/posture` | Merger or owner | Posture-check catalogue, effective interval / window / history retention, and the latest run (`compliance.PostureRun`: schedule/manual trigger, `triggered_by` identity, and per-check `pass`/`fail`/`skip`/`error`, detail, control ids, evidence refs); `?since=` (RFC 3339, `YYYY-MM-DD` or a look-back such as `168h`) adds every run since then, oldest first, capped at 1000 — see [Compliance](../compliance.md#posture-checks-catalogue) ([#11079](https://github.com/hivecommons/hive/issues/11079)) | `pkg/dashboard/api.go:351` | -| `POST` | `/api/compliance/posture/run` | Merger or owner | Run the posture checks now, attributed to the authenticated user, and record the pass in the history; audited as `compliance_posture_run`; `409` when no framework is selected or a pass is already running ([#11079](https://github.com/hivecommons/hive/issues/11079)) | `pkg/dashboard/api.go:352` | -| `GET` | `/api/compliance/posture/history` | Owner only | Posture history for `?since=`/`?until=` (default the last 30 days) as one series per check: points (`at`, `status`), status counts, `last_fail_at` and the latest result with detail and evidence refs; at most the 1000 most recent runs — see [Compliance](../compliance.md#evidence-exports-and-attestations) ([#11081](https://github.com/hivecommons/hive/issues/11081)) | `pkg/dashboard/api.go:353` | -| `GET` | `/api/compliance/export` | Owner only | Evidence download for `?since=`/`?until=`: `kind=controls` (`json`/`md`), `posture` (`json`/`csv`), `audit` (`json`), `config` (redacted effective config + sha256, `json`), `attestations` (`json`/`csv`) or `bundle` (`json`). Every format includes source, period, generator, selected profile versions, attesters, retention and a per-section SHA-256 manifest; audited as `compliance_export` with the SHA-256 of the delivered bytes ([#11081](https://github.com/hivecommons/hive/issues/11081), [#13582](https://github.com/hivecommons/hive/issues/13582)) | `pkg/dashboard/api.go:354` | -| `GET` | `/api/compliance/attestations` | Owner only | Owner attestations, newest first (`?framework=` filters) ([#11081](https://github.com/hivecommons/hive/issues/11081)) | `pkg/dashboard/api.go:355` | -| `POST` | `/api/compliance/attestations` | Owner only | Record `{"framework", "reviewed_on", "note"}` for the signed-in owner; audited as `compliance_attestation`; `201` with the attestation, `400` for an unknown framework, a bad or future date, or a note over 2000 characters ([#11081](https://github.com/hivecommons/hive/issues/11081)) | `pkg/dashboard/api.go:356` | -| `PUT` | `/api/config/governor/compliance` | Owner only | Settings → Compliance framework picker: `{"frameworks": [...]}` sets `compliance.frameworks` (empty list deselects all, absent key leaves it unchanged; unknown/duplicate ids are a `400` before any change); audited as `config_compliance`; returns the re-evaluated `compliance.Report` ([#11080](https://github.com/hivecommons/hive/issues/11080)) | `pkg/dashboard/api.go:529` | +| `GET` | `/api/config/sidebar` | Dashboard auth/session | Sidebar Get | `pkg/dashboard/api.go:359` | +| `PUT` | `/api/config/sidebar` | Dashboard auth/session | Sidebar Set | `pkg/dashboard/api.go:360` | +| `GET` | `/api/config/backends` | Dashboard auth/session | Backends | `pkg/dashboard/api.go:361` | +| `GET` | `/api/compliance/status` | Merger or owner | Evaluated compliance controls for the frameworks in `compliance.frameworks` (`compliance.Report`, JSON): per control `meets`/`deviates`/`off`/`not_covered` with current vs recommended value per mapped setting, a summary, and the non-certification disclaimer — see [Compliance](../compliance.md) ([#11078](https://github.com/hivecommons/hive/issues/11078)) | `pkg/dashboard/api.go:351` | +| `GET` | `/api/compliance/posture` | Merger or owner | Posture-check catalogue, effective interval / window / history retention, and the latest run (`compliance.PostureRun`: schedule/manual trigger, `triggered_by` identity, and per-check `pass`/`fail`/`skip`/`error`, detail, control ids, evidence refs); `?since=` (RFC 3339, `YYYY-MM-DD` or a look-back such as `168h`) adds every run since then, oldest first, capped at 1000 — see [Compliance](../compliance.md#posture-checks-catalogue) ([#11079](https://github.com/hivecommons/hive/issues/11079)) | `pkg/dashboard/api.go:352` | +| `POST` | `/api/compliance/posture/run` | Merger or owner | Run the posture checks now, attributed to the authenticated user, and record the pass in the history; audited as `compliance_posture_run`; `409` when no framework is selected or a pass is already running ([#11079](https://github.com/hivecommons/hive/issues/11079)) | `pkg/dashboard/api.go:353` | +| `GET` | `/api/compliance/posture/history` | Owner only | Posture history for `?since=`/`?until=` (default the last 30 days) as one series per check: points (`at`, `status`), status counts, `last_fail_at` and the latest result with detail and evidence refs; at most the 1000 most recent runs — see [Compliance](../compliance.md#evidence-exports-and-attestations) ([#11081](https://github.com/hivecommons/hive/issues/11081)) | `pkg/dashboard/api.go:354` | +| `GET` | `/api/compliance/export` | Owner only | Evidence download for `?since=`/`?until=`: `kind=controls` (`json`/`md`), `posture` (`json`/`csv`), `audit` (`json`), `config` (redacted effective config + sha256, `json`), `attestations` (`json`/`csv`) or `bundle` (`json`). Every format includes source, period, generator, selected profile versions, attesters, retention and a per-section SHA-256 manifest; audited as `compliance_export` with the SHA-256 of the delivered bytes ([#11081](https://github.com/hivecommons/hive/issues/11081), [#13582](https://github.com/hivecommons/hive/issues/13582)) | `pkg/dashboard/api.go:355` | +| `GET` | `/api/compliance/attestations` | Owner only | Owner attestations, newest first (`?framework=` filters) ([#11081](https://github.com/hivecommons/hive/issues/11081)) | `pkg/dashboard/api.go:356` | +| `POST` | `/api/compliance/attestations` | Owner only | Record `{"framework", "reviewed_on", "note"}` for the signed-in owner; audited as `compliance_attestation`; `201` with the attestation, `400` for an unknown framework, a bad or future date, or a note over 2000 characters ([#11081](https://github.com/hivecommons/hive/issues/11081)) | `pkg/dashboard/api.go:357` | +| `PUT` | `/api/config/governor/compliance` | Owner only | Settings → Compliance framework picker: `{"frameworks": [...]}` sets `compliance.frameworks` (empty list deselects all, absent key leaves it unchanged; unknown/duplicate ids are a `400` before any change); audited as `config_compliance`; returns the re-evaluated `compliance.Report` ([#11080](https://github.com/hivecommons/hive/issues/11080)) | `pkg/dashboard/api.go:530` | | `GET` | `/api/config/governor/threshold-scaling` | Owner only | Governor Threshold Scaling Get | `pkg/dashboard/api.go:201` | | `PUT` | `/api/config/governor/threshold-scaling` | Owner only | Governor Threshold Scaling Set | `pkg/dashboard/api.go:202` | @@ -99,13 +99,13 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `PUT` | `/api/config/governor/watchdog` | Owner only | Governor Watchdog | `pkg/dashboard/api.go:211` | | `GET` | `/api/config/escalation` | Owner only | Escalation Config Get | `pkg/dashboard/api.go:214` | | `PUT` | `/api/config/escalation` | Owner only | Escalation Config Set | `pkg/dashboard/api.go:215` | -| `GET` | `/api/config/write-surface` | Owner only | Lane write allowlist (`write_surface.allowlist`, [#9587](https://github.com/hivecommons/hive/issues/9587)): `allowlist`, `ops`, `warnings` | `pkg/dashboard/api.go:525` | -| `PUT` | `/api/config/write-surface` | Owner only | Replace the lane write allowlist; `{"allowlist": {}}` clears it; unknown operation or bad lane name is a 400 with nothing changed | `pkg/dashboard/api.go:526` | -| `GET` | `/api/config/reference-repos` | Owner only | `project.reference_repos` ([#18136](https://github.com/hivecommons/hive/issues/18136)): `reference_repos` (`{repo, write, write_token_file}` plus `derived_from` on a derived entry and, on every write entry, `credential_state`, `credential_reason` and `credential_login`, the GitHub account the writes appear under ([#18197](https://github.com/hivecommons/hive/issues/18197)), plus `credential_identity` (`bot`, `owner` or `token_file`) and `credential_note`, the one-line why ([#18516](https://github.com/hivecommons/hive/issues/18516)); always an array), `write_kinds`, `write_identity` (`project.remote_write_identity` with the default applied), `write_identities` and `bot_login` (the App bot login, when known) | `pkg/dashboard/api.go:556` | -| `PUT` | `/api/config/reference-repos` | Owner only | Replace `project.reference_repos`; `{"reference_repos": []}` clears it. Refused with a 400 and nothing changed when the config loader would reject the list (bare name, repo also in `project.repos`, duplicate, unknown write kind, token file without write) or when a write entry has no credential boot would accept — the same message boot exits 22 with — or when an entry carries a `write_token_file` the config file does not already hold for that repo (the path is operator-only; a dashboard write opt-in writes as the hive owner's connected GitHub account). Entries with `derived_from` ([#18139](https://github.com/hivecommons/hive/issues/18139)) are the request issue's grant: echo them back as served; changing one's write set, leaving one out, sending one the hive did not derive or adding a hand-written entry for the same repo is a 409 naming the issue to change instead ([#18161](https://github.com/hivecommons/hive/issues/18161)). They are never stored: the saved list holds the hand-written entries and the derived set is merged back in memory after the save. 500 when the file could not be written (proxy restored, nothing changed). On success the GitHub proxy's reference policies are replaced without a restart; audited as `config_reference_repos` | `pkg/dashboard/api.go:557` | -| `PUT` | `/api/config/reference-repos/write-identity` | Owner only | Set `project.remote_write_identity` ([#18516](https://github.com/hivecommons/hive/issues/18516)): body `{"write_identity": "bot"}`, one of `bot`, `bot_only`, `owner`. 400 on an unknown value, or when a hand-written write entry would have no credential under the new value (the message boot exits 22 with); nothing is stored then. 500 when the file could not be written. On success the reference repos are re-resolved before the response, which is the same body as `GET /api/config/reference-repos`; audited as `config_remote_write_identity` with `previous` and `write_identity` | `pkg/dashboard/api.go:559` | -| `GET` | `/api/config/prompt-sources` | Owner only | Repo-sourced prompt and definition gate ([#18490](https://github.com/hivecommons/hive/issues/18490)): `repos` (one row per managed repo, then any owner approval whose repo is no longer managed, each `{repo, managed, owner_approved, seed_allowed, allowed, approved_by, approved_at}`), `seed_enabled`, `seed_allowlist`, `trust_notice`, `seed_only_note` | `pkg/dashboard/api.go:568` | -| `PUT` | `/api/config/prompt-sources/owner-repos` | Owner only | `{"repo": "org/name", "allowed": true, "acknowledge_trust": true}` approves one of the hive's managed repos as a `prompt_source` / `definition_source` repo; `"allowed": false` revokes. 400 with nothing changed for a repo outside `project.repos` (still needs the seed edit), a malformed slug, or an approval without `acknowledge_trust: true`. Persisted to `variables.security.owner_github_prompt_repos` in the running config; audited as `config_prompt_source_repo`. Responds with the GET body | `pkg/dashboard/api.go:569` | +| `GET` | `/api/config/write-surface` | Owner only | Lane write allowlist (`write_surface.allowlist`, [#9587](https://github.com/hivecommons/hive/issues/9587)): `allowlist`, `ops`, `warnings` | `pkg/dashboard/api.go:526` | +| `PUT` | `/api/config/write-surface` | Owner only | Replace the lane write allowlist; `{"allowlist": {}}` clears it; unknown operation or bad lane name is a 400 with nothing changed | `pkg/dashboard/api.go:527` | +| `GET` | `/api/config/reference-repos` | Owner only | `project.reference_repos` ([#18136](https://github.com/hivecommons/hive/issues/18136)): `reference_repos` (`{repo, write, write_token_file}` plus `derived_from` on a derived entry and, on every write entry, `credential_state`, `credential_reason` and `credential_login`, the GitHub account the writes appear under ([#18197](https://github.com/hivecommons/hive/issues/18197)), plus `credential_identity` (`bot`, `owner` or `token_file`) and `credential_note`, the one-line why ([#18516](https://github.com/hivecommons/hive/issues/18516)); always an array), `write_kinds`, `write_identity` (`project.remote_write_identity` with the default applied), `write_identities` and `bot_login` (the App bot login, when known) | `pkg/dashboard/api.go:557` | +| `PUT` | `/api/config/reference-repos` | Owner only | Replace `project.reference_repos`; `{"reference_repos": []}` clears it. Refused with a 400 and nothing changed when the config loader would reject the list (bare name, repo also in `project.repos`, duplicate, unknown write kind, token file without write) or when a write entry has no credential boot would accept — the same message boot exits 22 with — or when an entry carries a `write_token_file` the config file does not already hold for that repo (the path is operator-only; a dashboard write opt-in writes as the hive owner's connected GitHub account). Entries with `derived_from` ([#18139](https://github.com/hivecommons/hive/issues/18139)) are the request issue's grant: echo them back as served; changing one's write set, leaving one out, sending one the hive did not derive or adding a hand-written entry for the same repo is a 409 naming the issue to change instead ([#18161](https://github.com/hivecommons/hive/issues/18161)). They are never stored: the saved list holds the hand-written entries and the derived set is merged back in memory after the save. 500 when the file could not be written (proxy restored, nothing changed). On success the GitHub proxy's reference policies are replaced without a restart; audited as `config_reference_repos` | `pkg/dashboard/api.go:558` | +| `PUT` | `/api/config/reference-repos/write-identity` | Owner only | Set `project.remote_write_identity` ([#18516](https://github.com/hivecommons/hive/issues/18516)): body `{"write_identity": "bot"}`, one of `bot`, `bot_only`, `owner`. 400 on an unknown value, or when a hand-written write entry would have no credential under the new value (the message boot exits 22 with); nothing is stored then. 500 when the file could not be written. On success the reference repos are re-resolved before the response, which is the same body as `GET /api/config/reference-repos`; audited as `config_remote_write_identity` with `previous` and `write_identity` | `pkg/dashboard/api.go:560` | +| `GET` | `/api/config/prompt-sources` | Owner only | Repo-sourced prompt and definition gate ([#18490](https://github.com/hivecommons/hive/issues/18490)): `repos` (one row per managed repo, then any owner approval whose repo is no longer managed, each `{repo, managed, owner_approved, seed_allowed, allowed, approved_by, approved_at}`), `seed_enabled`, `seed_allowlist`, `trust_notice`, `seed_only_note` | `pkg/dashboard/api.go:569` | +| `PUT` | `/api/config/prompt-sources/owner-repos` | Owner only | `{"repo": "org/name", "allowed": true, "acknowledge_trust": true}` approves one of the hive's managed repos as a `prompt_source` / `definition_source` repo; `"allowed": false` revokes. 400 with nothing changed for a repo outside `project.repos` (still needs the seed edit), a malformed slug, or an approval without `acknowledge_trust: true`. Persisted to `variables.security.owner_github_prompt_repos` in the running config; audited as `config_prompt_source_repo`. Responds with the GET body | `pkg/dashboard/api.go:570` | | `GET` | `/api/config/review` | Dashboard auth/session | Review Config Get | `pkg/dashboard/api.go:218` | | `PUT` | `/api/config/review` | Owner only | Review Config Set | `pkg/dashboard/api.go:221` | | `PUT` | `/api/config/governor/features` | Owner only | Governor Features | `pkg/dashboard/api.go:227` | diff --git a/src/docs/api-reference/dashboard-misc.md b/src/docs/api-reference/dashboard-misc.md index 31425b7ff6..28d1cfee3d 100644 --- a/src/docs/api-reference/dashboard-misc.md +++ b/src/docs/api-reference/dashboard-misc.md @@ -54,7 +54,7 @@ review are settled. | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| | `GET` | `/api/audit` | Read-write role | Audit Log — `{"entries": [...]}` envelope, newest first, capped at 200; response shape and the serve-time `user_name` field in [audit-log.md](../audit-log.md#get-apiaudit) | `pkg/dashboard/api.go:63` | -| `GET` | `/api/watchdog/activity` | Read-write role | Watchdog activity readout for the Health tab (#7254): `watchdog-*` audit actions over `?days=` (default 30, clamped to 90) — total / taken / observed / `byAction`, a zero-filled per-day `daily` histogram, per-agent `agents` liveness, and the Observe → Heal `promotion` hint; see [agent-watchdog.md](../agent-watchdog.md#watchdog-activity-strip) | `pkg/dashboard/api.go:498` | +| `GET` | `/api/watchdog/activity` | Read-write role | Watchdog activity readout for the Health tab (#7254): `watchdog-*` audit actions over `?days=` (default 30, clamped to 90) — total / taken / observed / `byAction`, a zero-filled per-day `daily` histogram, per-agent `agents` liveness, and the Observe → Heal `promotion` hint; see [agent-watchdog.md](../agent-watchdog.md#watchdog-activity-strip) | `pkg/dashboard/api.go:499` | | `POST` | `/api/presence` | Dashboard auth/session | Presence | `pkg/dashboard/api.go:66` | | `POST` | `/api/upgrade/announce` | Owner role | Announce a pod roll before it happens ([#15788](https://github.com/hivecommons/hive/issues/15788)): body `{"target": "", "source": "hub"|"operator", "reason": "..."}` (`version` is an alias of `target`; all fields optional). Marks `/api/status`/`/api/version` `upgradeProgress` as `state: pulling, phase: announced` with the target and publishes an SSE `upgrading` event so every open dashboard shows the upgrade animation; a SIGTERM afterwards (or with no announce at all) publishes `phase: restarting` from the same record. The hub sends the same announce through the heartbeat response (`upgrade_announce`) for hub-managed hives; an announce with no kill expires after 15 minutes. Returns `{ok, upgradeProgress}` | `pkg/dashboard/api.go:69` | | `GET` | `/api/prompt-history` | Dashboard auth/session | Prompt History | `pkg/dashboard/api.go:67` | @@ -69,18 +69,18 @@ review are settled. | `GET` | `/api/convergence/soak` | Owner only | Convergence Soak Status | `pkg/dashboard/api.go:245` | -| `POST` | `/api/plan/from-issue` | Dashboard auth/session | Plan From Issue | `pkg/dashboard/api.go:450` | -| `GET` | `/api/plan/{epicID}` | Dashboard auth/session | Plan Tree | `pkg/dashboard/api.go:453` | -| `POST` | `/api/plan/{epicID}/approve` | Owner only | Plan Approve | `pkg/dashboard/api.go:454` | -| `POST` | `/api/plan/{epicID}/reject` | Owner only | Plan Reject | `pkg/dashboard/api.go:456` | -| `POST` | `/api/plan/{epicID}/child/{childID}` | Owner only | Plan Child Action | `pkg/dashboard/api.go:457` | +| `POST` | `/api/plan/from-issue` | Dashboard auth/session | Plan From Issue | `pkg/dashboard/api.go:451` | +| `GET` | `/api/plan/{epicID}` | Dashboard auth/session | Plan Tree | `pkg/dashboard/api.go:454` | +| `POST` | `/api/plan/{epicID}/approve` | Owner only | Plan Approve | `pkg/dashboard/api.go:455` | +| `POST` | `/api/plan/{epicID}/reject` | Owner only | Plan Reject | `pkg/dashboard/api.go:457` | +| `POST` | `/api/plan/{epicID}/child/{childID}` | Owner only | Plan Child Action | `pkg/dashboard/api.go:458` | | `POST` | `/api/linear/agent/install` | Owner only | Linear Agent Install (OAuth start) | `pkg/dashboard/api_linear_agent.go:215` | | `GET` | `/api/linear/agent/status` | Owner only | Linear Agent Status | `pkg/dashboard/api_linear_agent.go:216` | | `POST` | `/api/linear/agent/disconnect` | Owner only | Linear Agent Disconnect | `pkg/dashboard/api_linear_agent.go:217` | | `GET` | `/api/upstream-watch` | Owner only | Upstream-watch divergence: per watched fork the upstream followed, the watermark and last-run time, surfaced/ported/dismissed/skipped counts, and the recent upstream refs with their upstream URL, diff URL, fork issue number and state. Read-only — it reads the config and the watch state file, never GitHub. Also carries `interval`, `project_repos` and each repo's configured entry (`config`) for the editor. | `pkg/dashboard/api.go:288` | | `PUT` | `/api/config/upstream-watch` | Owner only | Upstream Watch Config Update: edit `upstream_watch` from the Features tab. Body `{enabled?, interval?, repos?: {: {upstream?, sources?, pr_labels?, max_issues_per_run?, label?} \| null}}` — absent keys are unchanged, `null` removes a repo, keys are stored as the bare repo name. Validated with the loader's rules before the config changes (400 on failure), then persisted and audited as `config_upstream_watch`. | `pkg/dashboard/api.go:289` | -| `GET` | `/api/hotspots` | Dashboard auth/session | Merge-hotspot advisor report (`?repo=owner/name` optional): files repeatedly touched by concurrent PRs over the last `governor.hotspot_window_days`, each with `prs` (distinct PRs), `pr_numbers`, `overlaps` (PR pairs open at the same time), `conflicts` (rebase conflicts blamed on the file), `lines`, `kind` (`code`/`doc`/`lock`/`generated`/`data`), `score`, `symbol_groups`, `recommendation` (`split-code`/`split-doc`/`split-source`/`report-only`/`none`), `reason`, `generated_from`, `source_files` (files under `generated_from`, when known), `issue_number`/`issue_url` of the modularize issue filed, `last_updated`; top-level `count`/`actionable`/`filed`. Derived from the merge train's own PR file lists and the rebase follow-through's conflict records — never lists PRs or files from GitHub. See [operator-reference.md § Merge-hotspot advisor](../operator-reference.md#merge-hotspot-advisor-governorhotspot_). | `pkg/dashboard/api.go:536` | +| `GET` | `/api/hotspots` | Dashboard auth/session | Merge-hotspot advisor report (`?repo=owner/name` optional): files repeatedly touched by concurrent PRs over the last `governor.hotspot_window_days`, each with `prs` (distinct PRs), `pr_numbers`, `overlaps` (PR pairs open at the same time), `conflicts` (rebase conflicts blamed on the file), `lines`, `kind` (`code`/`doc`/`lock`/`generated`/`data`), `score`, `symbol_groups`, `recommendation` (`split-code`/`split-doc`/`split-source`/`report-only`/`none`), `reason`, `generated_from`, `source_files` (files under `generated_from`, when known), `issue_number`/`issue_url` of the modularize issue filed, `last_updated`; top-level `count`/`actionable`/`filed`. Derived from the merge train's own PR file lists and the rebase follow-through's conflict records — never lists PRs or files from GitHub. See [operator-reference.md § Merge-hotspot advisor](../operator-reference.md#merge-hotspot-advisor-governorhotspot_). | `pkg/dashboard/api.go:537` | | `GET` | `/api/widget` | Dashboard auth/session | Widget | `pkg/dashboard/api.go:99` | | `GET` | `/api/pane/{agent}` | Dashboard auth/session | Pane | `pkg/dashboard/api.go:104` | | `GET` | `/api/role` | Dashboard auth/session | Role | `pkg/dashboard/api.go:118` | @@ -91,11 +91,11 @@ review are settled. | `GET` | `/api/stage-tracker` | Dashboard auth/session | Stage Tracker: every open issue and pull request of the watched repos for the Hive activity monitor — actionable, held, claimed, in-progress, covered-by-PR, filtered (`needs-*`), draft and exempt-labelled items alike, each with `stage`, `stage_since`, `labels`, `created_at`, `author_kind`, `modifiers`, `claimant: {kind: hive-agent|clanker|person, login, agent, hive, since, source: claim-ledger|claim-comment|assignee|kick-history|author}` naming who holds a claimed / in-progress issue or a PR under review or rework (absent when nobody is named; mirrored onto `linked_prs[]`), (PRs) `sentinel_alert` / `sentinel_findings` / `sentinel_reason` when the sentinel flagged the PR, `decision_needed` on a row parked on a person (085 / 045 / 015, the needs-human pill; mirrored onto the issue's `linked_prs[]` entry): `{question, asked_by, since, blocker, blocker_reason, options: [{action, label, enabled, reason_if_disabled}]}` — the reviewer's own decision question when the verdict record has one, the blocker in plain words, and the applicable actions under the row context menu's action ids (`decide:delegate` first), (PRs) `lineage` on the hive's copy of an adopted PR — `{kind: adopted|superseded|rebased-by-hive, from_number, from_url, from_author, from_author_kind, to_number, to_url, at, reason}`, derived from the stage store's adoption record or the `hive/adopt-` head branch, mirrored onto the issue's `linked_prs[]` entry; absent on every other row — and (issues) `linked_prs`; items with no stage yet report stage `0` "Open"; `needs_human_why` `{source: filed-for-help|decision-pending|level-gate|hive-hold|needs-approval|triage|author|needs-human, reason}` on every row a person must move (with `needs_human: true`; `filed_for_help` names the agent whose marker is in an unclaimed issue's body); `needs_human_labels` is the "a person must act" label set behind the monitor's Needs human facet (the same list as `/api/status.labelPresets[needs-human]`); `recently_merged` lists the PRs (`repo`, `number`, `merged_at`) whose `pr_merged` audit entry is under 30 minutes old, so a client diffing two payloads can tell a merge from a close; a PR in a conflict-aware merge train carries `merge_train` `{id, state, front, position, size, attempt, max_attempts, overlap_files, ahead, length, head_number, head_state, head_reason, head_since, eta_s, eta_at, eta_basis, late, stalled, stalled_s}` — `head_state` one of `needs-human` / `ci` / `soaking` / `ready` / `merging` / `fixing` / `unknown` with `head_reason` in plain words; `eta_s` / `eta_at` the estimated wait for this member's own merge attempt (own remaining soak + each PR ahead's remaining soak or one sweep + the next sweep tick; absent while the head waits on a person or CI), `eta_at` anchored to the member's first estimate at its position so a countdown survives polls, `eta_basis` its short reading ("2 ahead · head soaking 12m · next sweep in 40s"), `late` once now has overrun the first estimate twice over, `stalled` / `stalled_s` once the head has sat longer than `governor.merge_train_stall_warn_s` ([#15395](https://github.com/hivecommons/hive/issues/15395)); a PR the queue holds because another open PR declares the same `Fixes #N` carries no `merge_train` and a `merge_gate` of `{state: "duplicate-of:", duplicate_of, duplicate_issue}` plus the `needs-decision` modifier (the queue keeps one PR per issue: green first, then the earlier-opened); a PR GitHub reports conflicting on its own, or one under repair (stage/070, 071, 072, 074, 085, or a red required check), carries no `merge_train` and is not counted in any member's `size` / `length` — a repaired member the view dropped carries `left_train: {why: fixing|needs-author|returned-to-contributor|adopted-by-hive|needs-decision|checks-failing, note}` instead (mirrored onto the issue's `linked_prs[]` entry), and a train left with one member reports no `merge_train` at all; a PR short of the merge queue (below stage/080) the planner ordered rides no train either — it carries `overlap: {behind, with, files, note}` ("overlaps #15637 (sidebar.html, index.html) — will queue behind it") and no `merge_train`, and counts in no member's `size` — the state slugs (`front`, `queued-behind`) are payload values only, the SPA renders ordinal places ("Queued for merge · 1st of 2", with the train's tag when more than one train is on the page). Served from a server-side cache rebuilt at most every `dashboard.stage_tracker.cache_ttl_s` (default `governor.eval_interval_s`) from the spoke's existing snapshot — a request never calls GitHub. Carries `generated_at`, `source` (`cache` or `fresh`), `cache_ttl_s`, an `ETag` and `Cache-Control: private, max-age=`; `If-None-Match` yields 304. Each hit is recorded under REST caller `dashboard:stage-tracker` so `/api/gh-rate-limits` shows it charged nothing. | `pkg/dashboard/api.go:172` | | `GET` | `/api/matrix/lines` | Dashboard auth/session | Matrix Lines (deprecated name, see [Published-checkpoint regions](#published-checkpoint-regions)): serve bounded backlog of pushed lines behind dashboard.matrix with repo allowlist filtering. `max` counts only lines the repo allowlist admits, so a page is never emptied by filtered-out lines. A client paging with `max` should use the last returned line's `seq` as its next `since`, not the top-level `seq`, which is the source's latest sequence number and would skip lines still past the page. `more` is true only while another line the caller may see remains past the page; stop paging when it is false. | `pkg/dashboard/api.go:173` | | `POST` | `/api/prs/{owner}/{repo}/{number}/queue-automerge` | Merger/owner role | Queue PRAuto Merge | `pkg/dashboard/api.go:174` | -| `GET` | `/api/inference/models/{backend}` | Dashboard auth/session | Inference Models | `pkg/dashboard/api.go:363` | -| `GET` | `/api/hive-id` | Dashboard auth/session | Hive IDGet | `pkg/dashboard/api.go:427` | -| `PUT` | `/api/hive-id` | Owner only | Hive IDSet | `pkg/dashboard/api.go:428` | -| `POST` | `/api/chat` | Dashboard auth/session | Chat | `pkg/dashboard/api.go:459` | -| `GET` | `/api/auth/token` | Public | Auth Token | `pkg/dashboard/api.go:493` | +| `GET` | `/api/inference/models/{backend}` | Dashboard auth/session | Inference Models | `pkg/dashboard/api.go:364` | +| `GET` | `/api/hive-id` | Dashboard auth/session | Hive IDGet | `pkg/dashboard/api.go:428` | +| `PUT` | `/api/hive-id` | Owner only | Hive IDSet | `pkg/dashboard/api.go:429` | +| `POST` | `/api/chat` | Dashboard auth/session | Chat | `pkg/dashboard/api.go:460` | +| `GET` | `/api/auth/token` | Public | Auth Token | `pkg/dashboard/api.go:494` | | `GET` | `/api/v1/` | GitHub token | Contributor v1 API dispatcher | `pkg/dashboard/api_contribute.go:351` | | `POST` | `/api/v1/` | GitHub token | Contributor v1 API dispatcher | `pkg/dashboard/api_contribute.go:352` | | `GET` | `/api/docs` | Dashboard auth/session | APIDocs | `pkg/dashboard/api_contribute.go:353` | diff --git a/src/docs/api-reference/inception.md b/src/docs/api-reference/inception.md index 2e78c76a45..b84277b39b 100644 --- a/src/docs/api-reference/inception.md +++ b/src/docs/api-reference/inception.md @@ -7,17 +7,17 @@ The inception API was retired in favour of [Inception (spek) sessions](sessions. | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| -| `POST` | `/api/inception/start` | Dashboard auth/session | Retired (was: Inception Start): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:432` | -| `POST` | `/api/inception/scan` | Dashboard auth/session | Retired (was: Inception Scan): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:433` | -| `GET` | `/api/inception/state` | Dashboard auth/session | Retired (was: Inception State): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:434` | -| `POST` | `/api/inception/questions` | Dashboard auth/session | Retired (was: Inception Set Questions): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:435` | -| `POST` | `/api/inception/answer` | Dashboard auth/session | Retired (was: Inception Answer): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:436` | -| `POST` | `/api/inception/facts` | Dashboard auth/session | Retired (was: Inception Record Facts): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:437` | -| `GET` | `/api/inception/scaffold` | Dashboard auth/session | Retired (was: Inception Scaffold): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:438` | -| `POST` | `/api/inception/approve` | Dashboard auth/session | Retired (was: Inception Approve): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:439` | -| `POST` | `/api/inception/reset` | Dashboard auth/session | Retired (was: Inception Reset): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:440` | -| `GET` | `/api/inception/ideation-facts` | Dashboard auth/session | Retired (was: Inception Ideation Facts): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:441` | -| `GET` | `/api/inception/download` | Dashboard auth/session | Retired (was: Inception Download): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:442` | -| `GET` | `/api/inception/has-files` | Dashboard auth/session | Retired (was: Inception Has Files): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:443` | -| `PUT` | `/api/inception/wiki-name` | Dashboard auth/session | Retired (was: Inception Rename Wiki): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:444` | -| `POST` | `/api/inception/import` | Dashboard auth/session | Retired (was: Inception Import): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:445` | +| `POST` | `/api/inception/start` | Dashboard auth/session | Retired (was: Inception Start): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:433` | +| `POST` | `/api/inception/scan` | Dashboard auth/session | Retired (was: Inception Scan): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:434` | +| `GET` | `/api/inception/state` | Dashboard auth/session | Retired (was: Inception State): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:435` | +| `POST` | `/api/inception/questions` | Dashboard auth/session | Retired (was: Inception Set Questions): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:436` | +| `POST` | `/api/inception/answer` | Dashboard auth/session | Retired (was: Inception Answer): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:437` | +| `POST` | `/api/inception/facts` | Dashboard auth/session | Retired (was: Inception Record Facts): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:438` | +| `GET` | `/api/inception/scaffold` | Dashboard auth/session | Retired (was: Inception Scaffold): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:439` | +| `POST` | `/api/inception/approve` | Dashboard auth/session | Retired (was: Inception Approve): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:440` | +| `POST` | `/api/inception/reset` | Dashboard auth/session | Retired (was: Inception Reset): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:441` | +| `GET` | `/api/inception/ideation-facts` | Dashboard auth/session | Retired (was: Inception Ideation Facts): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:442` | +| `GET` | `/api/inception/download` | Dashboard auth/session | Retired (was: Inception Download): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:443` | +| `GET` | `/api/inception/has-files` | Dashboard auth/session | Retired (was: Inception Has Files): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:444` | +| `PUT` | `/api/inception/wiki-name` | Dashboard auth/session | Retired (was: Inception Rename Wiki): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:445` | +| `POST` | `/api/inception/import` | Dashboard auth/session | Retired (was: Inception Import): answers `410 Gone` pointing to `/api/sessions` | `pkg/dashboard/api.go:446` | diff --git a/src/docs/api-reference/knowledge.md b/src/docs/api-reference/knowledge.md index af6a86de32..d07237e6a2 100644 --- a/src/docs/api-reference/knowledge.md +++ b/src/docs/api-reference/knowledge.md @@ -5,39 +5,39 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| -| `GET` | `/api/knowledge` | Dashboard auth/session | Paginated knowledge facts: `type` filter, `limit` (default 50, max 200; invalid/non-positive values use the default), `offset` (default 0). Returns `enabled`, `facts`, `count` (this page), `total`, `limit`, `offset`, `has_more`; ordered by layer then slug. Offsets are not snapshot cursors: concurrent edits may shift pages. | `pkg/dashboard/api.go:365` | -| `GET` | `/api/knowledge/export` | Dashboard auth/session | Knowledge Export | `pkg/dashboard/api.go:366` | -| `POST` | `/mcp/knowledge` | Public (read-only) when the dashboard setting or `HIVE_PUBLIC_KNOWLEDGE` is on; otherwise 404 to a signed-in caller and 401 to one who is not | Public Knowledge MCP endpoint — `initialize`, `tools/list`, `tools/call` for `knowledge_search`/`knowledge_toc`/`knowledge_get`/`knowledge_export` ([docs](../public-knowledge-mcp.md)) | `pkg/dashboard/api.go:376` | -| `GET` | `/api/knowledge/search` | Dashboard auth/session | Knowledge Search | `pkg/dashboard/api.go:367` | -| `GET` | `/api/knowledge/toc` | Dashboard auth/session | Scoped knowledge table of contents: capped, body-free entries (`id`, `title`, `type`, `layer`, `repo`, `tags`, `status`, `confidence`, `updated`, `size_bytes`, `source`) plus `total`/`returned`/`truncated`. Query: `layers`, `repos`, `types`, `tags` (comma-separated), `limit` (default 50, max 200), `include_states` (operator opt-in for `draft`/`deprecated`/`superseded`/`all`), `format=prompt` with `max_chars` for a bounded markdown rendering, `agent` to apply that agent's `knowledge.agent_scopes` entry (the other parameters can only narrow it). Approved knowledge only by default ([docs](../knowledge-toc.md)) | `pkg/dashboard/api.go:368` | -| `GET` | `/api/knowledge/advisor/summary` | Dashboard auth/session (read or higher) | Read-only knowledge-advisor rank-versus-holdout summary: `window` (`since`, `first_decision`, `last_decision`, `rank_mode_start`, `decisions`), `settings` (`enabled`, `mode`, `model`, `holdout_percent`, `max_calls_per_day`, `max_calls_per_agent_hour`, `candidates`, `on_error`; never the endpoint or key), `counts` (`by_mode`, `by_arm`, `by_outcome`), `arms` (per-arm closed-bead `beads` and mean fix attempts, CI failures and kicks from `Lane.AdvisorArmSummary()`) with `mixed` and `none` listed separately, `cost` (mean latency and tokens where records carry them), and a `small_n`/`caveat` pair. Counts and means only: no slugs, refs, agents or content. Query: `since` (RFC 3339) narrows the decision counts and cost, not the bead means ([docs](../retro-lane.md#reading-the-comparison-from-the-dashboard)) | `pkg/dashboard/api.go:369` | -| `GET` | `/api/knowledge/effective` | Dashboard auth/session | Effective knowledge for one agent (`agent` required): the agent's `knowledge.agent_scopes` entry (unrestricted when it has none) intersected with the request scope (approved only unless `include_states` is set). Returns `scope` (resolved scope applied, with `configured`), `included` TOC entries, `excluded` entries each with a `reason` (`lifecycle`, `layer`, `repo`, `type` or `tag` — first failing check, in that order), `included_total`/`excluded_total`/`included_returned`/`excluded_returned` and `truncated`; `limit` caps each list (default 50, max 200) ([docs](../knowledge-toc.md#effective-knowledge)) | `pkg/dashboard/api.go:370` | -| `GET` | `/api/knowledge/entry/{id}` | Dashboard auth/session | Full read of one knowledge entry: `markdown` (front-matter plus body) and the fact. Takes the same scope, `include_states` and `agent` query as the table of contents and returns 404 for an entry outside it ([docs](../knowledge-toc.md)) | `pkg/dashboard/api.go:371` | -| `POST` | `/api/knowledge/cli-memory/drain-legacy` | Owner only | One-shot drain of the shared home's legacy Claude memory (`/data/home/.claude/projects/*/memory`) into `state: draft` entries in `bead-synth-wiki`, tagged `cli-memory` and `agent:shared`, deduplicated by content hash. Body `{"truncate": bool}` (default false) empties only files whose every fact is now stored. Returns `store`, `agent`, `sources`, `drained`, `dupes`, `skipped`, `truncate`, `truncated`, `kept`, `errors`; 409 when the vault is not connected. Audited as `knowledge_drain_legacy_memory` ([docs](../knowledge-lifecycle.md#auto-memory-drafts)) | `pkg/dashboard/api.go:373` | -| `GET` | `/api/knowledge/public` | Dashboard auth/session | Public Knowledge MCP sharing status (`enabled`, `tags`, `source`, endpoint URL) | `pkg/dashboard/api.go:377` | -| `PUT` | `/api/knowledge/public` | Owner only | Persist public Knowledge MCP sharing setting; overrides env vars until changed | `pkg/dashboard/api.go:378` | -| `GET` | `/api/knowledge/health` | Dashboard auth/session | Knowledge Health | `pkg/dashboard/api.go:379` | -| `GET` | `/api/knowledge/stats` | Dashboard auth/session | Knowledge Stats | `pkg/dashboard/api.go:380` | -| `GET` | `/api/knowledge/graph` | Dashboard auth/session | Knowledge Graph | `pkg/dashboard/api.go:381` | -| `GET` | `/api/knowledge/fact-history` | Dashboard auth/session | Fact History | `pkg/dashboard/api.go:382` | -| `POST` | `/api/knowledge/create` | Dashboard auth/session | Create one fact (`title`, `body`, `type`, `tags`, `layer`, `confidence`, `state`). `state` is `approved` (default) or `draft`; a draft is written with `state: draft` into the local channel named by `layer` (400 when there is none, 409 when its title already names an entry). A request tagged `cli-memory` must be a draft carrying only `cli-memory`, `agent:`, `cli:`, `memhash:` and `repo:/` tags (400 otherwise) | `pkg/dashboard/api.go:383` | -| `POST` | `/api/knowledge/import` | Dashboard auth/session | Knowledge Import | `pkg/dashboard/api.go:384` | -| `POST` | `/api/knowledge/promote` | Dashboard auth/session | Knowledge Promote | `pkg/dashboard/api.go:390` | -| `GET` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs List | `pkg/dashboard/api.go:391` | -| `POST` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs Add | `pkg/dashboard/api.go:392` | -| `DELETE` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs Remove | `pkg/dashboard/api.go:393` | -| `PUT` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Update | `pkg/dashboard/api.go:394` | -| `DELETE` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Delete | `pkg/dashboard/api.go:395` | -| `GET` | `/api/knowledge/{layer}` | Dashboard auth/session | Knowledge Layer | `pkg/dashboard/api.go:396` | -| `GET` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Fact | `pkg/dashboard/api.go:397` | -| `PUT` | `/api/knowledge/enabled` | Owner only | Knowledge Toggle | `pkg/dashboard/api.go:398` | -| `GET` | `/api/knowledge/bead-synthesizer` | Dashboard auth/session | Bead Synth Status | `pkg/dashboard/api.go:399` | -| `PUT` | `/api/knowledge/bead-synthesizer/enabled` | Owner only | Bead Synth Toggle | `pkg/dashboard/api.go:400` | -| `GET` | `/api/knowledge/vaults` | Dashboard auth/session | Vaults List | `pkg/dashboard/api.go:401` | -| `POST` | `/api/knowledge/vaults` | Owner only | Vaults Connect | `pkg/dashboard/api.go:402` | -| `DELETE` | `/api/knowledge/vaults` | Dashboard auth/session | Vaults Disconnect | `pkg/dashboard/api.go:403` | -| `POST` | `/api/knowledge/vaults/reindex` | Dashboard auth/session | Vaults Reindex | `pkg/dashboard/api.go:404` | -| `GET` | `/api/knowledge/vaults/{name}/facts` | Dashboard auth/session | Vault Facts | `pkg/dashboard/api.go:405` | +| `GET` | `/api/knowledge` | Dashboard auth/session | Paginated knowledge facts: `type` filter, `limit` (default 50, max 200; invalid/non-positive values use the default), `offset` (default 0). Returns `enabled`, `facts`, `count` (this page), `total`, `limit`, `offset`, `has_more`; ordered by layer then slug. Offsets are not snapshot cursors: concurrent edits may shift pages. | `pkg/dashboard/api.go:366` | +| `GET` | `/api/knowledge/export` | Dashboard auth/session | Knowledge Export | `pkg/dashboard/api.go:367` | +| `POST` | `/mcp/knowledge` | Public (read-only) when the dashboard setting or `HIVE_PUBLIC_KNOWLEDGE` is on; otherwise 404 to a signed-in caller and 401 to one who is not | Public Knowledge MCP endpoint — `initialize`, `tools/list`, `tools/call` for `knowledge_search`/`knowledge_toc`/`knowledge_get`/`knowledge_export` ([docs](../public-knowledge-mcp.md)) | `pkg/dashboard/api.go:377` | +| `GET` | `/api/knowledge/search` | Dashboard auth/session | Knowledge Search | `pkg/dashboard/api.go:368` | +| `GET` | `/api/knowledge/toc` | Dashboard auth/session | Scoped knowledge table of contents: capped, body-free entries (`id`, `title`, `type`, `layer`, `repo`, `tags`, `status`, `confidence`, `updated`, `size_bytes`, `source`) plus `total`/`returned`/`truncated`. Query: `layers`, `repos`, `types`, `tags` (comma-separated), `limit` (default 50, max 200), `include_states` (operator opt-in for `draft`/`deprecated`/`superseded`/`all`), `format=prompt` with `max_chars` for a bounded markdown rendering, `agent` to apply that agent's `knowledge.agent_scopes` entry (the other parameters can only narrow it). Approved knowledge only by default ([docs](../knowledge-toc.md)) | `pkg/dashboard/api.go:369` | +| `GET` | `/api/knowledge/advisor/summary` | Dashboard auth/session (read or higher) | Read-only knowledge-advisor rank-versus-holdout summary: `window` (`since`, `first_decision`, `last_decision`, `rank_mode_start`, `decisions`), `settings` (`enabled`, `mode`, `model`, `holdout_percent`, `max_calls_per_day`, `max_calls_per_agent_hour`, `candidates`, `on_error`; never the endpoint or key), `counts` (`by_mode`, `by_arm`, `by_outcome`), `arms` (per-arm closed-bead `beads` and mean fix attempts, CI failures and kicks from `Lane.AdvisorArmSummary()`) with `mixed` and `none` listed separately, `cost` (mean latency and tokens where records carry them), and a `small_n`/`caveat` pair. Counts and means only: no slugs, refs, agents or content. Query: `since` (RFC 3339) narrows the decision counts and cost, not the bead means ([docs](../retro-lane.md#reading-the-comparison-from-the-dashboard)) | `pkg/dashboard/api.go:370` | +| `GET` | `/api/knowledge/effective` | Dashboard auth/session | Effective knowledge for one agent (`agent` required): the agent's `knowledge.agent_scopes` entry (unrestricted when it has none) intersected with the request scope (approved only unless `include_states` is set). Returns `scope` (resolved scope applied, with `configured`), `included` TOC entries, `excluded` entries each with a `reason` (`lifecycle`, `layer`, `repo`, `type` or `tag` — first failing check, in that order), `included_total`/`excluded_total`/`included_returned`/`excluded_returned` and `truncated`; `limit` caps each list (default 50, max 200) ([docs](../knowledge-toc.md#effective-knowledge)) | `pkg/dashboard/api.go:371` | +| `GET` | `/api/knowledge/entry/{id}` | Dashboard auth/session | Full read of one knowledge entry: `markdown` (front-matter plus body) and the fact. Takes the same scope, `include_states` and `agent` query as the table of contents and returns 404 for an entry outside it ([docs](../knowledge-toc.md)) | `pkg/dashboard/api.go:372` | +| `POST` | `/api/knowledge/cli-memory/drain-legacy` | Owner only | One-shot drain of the shared home's legacy Claude memory (`/data/home/.claude/projects/*/memory`) into `state: draft` entries in `bead-synth-wiki`, tagged `cli-memory` and `agent:shared`, deduplicated by content hash. Body `{"truncate": bool}` (default false) empties only files whose every fact is now stored. Returns `store`, `agent`, `sources`, `drained`, `dupes`, `skipped`, `truncate`, `truncated`, `kept`, `errors`; 409 when the vault is not connected. Audited as `knowledge_drain_legacy_memory` ([docs](../knowledge-lifecycle.md#auto-memory-drafts)) | `pkg/dashboard/api.go:374` | +| `GET` | `/api/knowledge/public` | Dashboard auth/session | Public Knowledge MCP sharing status (`enabled`, `tags`, `source`, endpoint URL) | `pkg/dashboard/api.go:378` | +| `PUT` | `/api/knowledge/public` | Owner only | Persist public Knowledge MCP sharing setting; overrides env vars until changed | `pkg/dashboard/api.go:379` | +| `GET` | `/api/knowledge/health` | Dashboard auth/session | Knowledge Health | `pkg/dashboard/api.go:380` | +| `GET` | `/api/knowledge/stats` | Dashboard auth/session | Knowledge Stats | `pkg/dashboard/api.go:381` | +| `GET` | `/api/knowledge/graph` | Dashboard auth/session | Knowledge Graph | `pkg/dashboard/api.go:382` | +| `GET` | `/api/knowledge/fact-history` | Dashboard auth/session | Fact History | `pkg/dashboard/api.go:383` | +| `POST` | `/api/knowledge/create` | Dashboard auth/session | Create one fact (`title`, `body`, `type`, `tags`, `layer`, `confidence`, `state`). `state` is `approved` (default) or `draft`; a draft is written with `state: draft` into the local channel named by `layer` (400 when there is none, 409 when its title already names an entry). A request tagged `cli-memory` must be a draft carrying only `cli-memory`, `agent:`, `cli:`, `memhash:` and `repo:/` tags (400 otherwise) | `pkg/dashboard/api.go:384` | +| `POST` | `/api/knowledge/import` | Dashboard auth/session | Knowledge Import | `pkg/dashboard/api.go:385` | +| `POST` | `/api/knowledge/promote` | Dashboard auth/session | Knowledge Promote | `pkg/dashboard/api.go:391` | +| `GET` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs List | `pkg/dashboard/api.go:392` | +| `POST` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs Add | `pkg/dashboard/api.go:393` | +| `DELETE` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs Remove | `pkg/dashboard/api.go:394` | +| `PUT` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Update | `pkg/dashboard/api.go:395` | +| `DELETE` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Delete | `pkg/dashboard/api.go:396` | +| `GET` | `/api/knowledge/{layer}` | Dashboard auth/session | Knowledge Layer | `pkg/dashboard/api.go:397` | +| `GET` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Fact | `pkg/dashboard/api.go:398` | +| `PUT` | `/api/knowledge/enabled` | Owner only | Knowledge Toggle | `pkg/dashboard/api.go:399` | +| `GET` | `/api/knowledge/bead-synthesizer` | Dashboard auth/session | Bead Synth Status | `pkg/dashboard/api.go:400` | +| `PUT` | `/api/knowledge/bead-synthesizer/enabled` | Owner only | Bead Synth Toggle | `pkg/dashboard/api.go:401` | +| `GET` | `/api/knowledge/vaults` | Dashboard auth/session | Vaults List | `pkg/dashboard/api.go:402` | +| `POST` | `/api/knowledge/vaults` | Owner only | Vaults Connect | `pkg/dashboard/api.go:403` | +| `DELETE` | `/api/knowledge/vaults` | Dashboard auth/session | Vaults Disconnect | `pkg/dashboard/api.go:404` | +| `POST` | `/api/knowledge/vaults/reindex` | Dashboard auth/session | Vaults Reindex | `pkg/dashboard/api.go:405` | +| `GET` | `/api/knowledge/vaults/{name}/facts` | Dashboard auth/session | Vault Facts | `pkg/dashboard/api.go:406` | | `GET` | `/api/config/knowledge/connectors` | Dashboard auth/session | Knowledge connectors config (name, type, layer, scope, env/file auth reference) and registered types | `pkg/dashboard/api.go` | | `PUT` | `/api/config/knowledge/connectors` | Owner only | Replace `knowledge.connectors` after validation; inline secrets rejected | `pkg/dashboard/api.go` | | `GET` | `/api/config/knowledge/connectors/status` | Dashboard auth/session | Per-connector status pill, last sync, pages/facts, last error, `running` and the live `progress` block (phase, items_done/items_total, current item, started_at; see [knowledge-connectors.md](../knowledge-connectors.md#api)), plus the `publish` mirror status | `pkg/dashboard/api.go` | @@ -47,19 +47,19 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `PUT` | `/api/config/knowledge/agent-scopes` | Owner only | Replace `knowledge.agent_scopes` after validating layer and state names; persisted and audited as `config_knowledge_agent_scopes` | `pkg/dashboard/api.go` | | `GET` | `/api/config/knowledge/pipeline` | Owner only | Scalar bead synthesizer, curator, code map and primer settings, plus the read-only engine, vault paths and primer merge strategy ([docs](../settings.md#knowledge)) | `pkg/dashboard/api.go` | | `PUT` | `/api/config/knowledge/pipeline` | Owner only | Update those settings after `config.ValidateKnowledgePipeline`; 0 or empty restores the default; the bead synthesizer switch applies at once, the rest after a restart; audited as `config_knowledge_pipeline` | `pkg/dashboard/api.go` | -| `GET` | `/api/knowledge/git-sources` | Dashboard auth/session | Git Sources List | `pkg/dashboard/api.go:415` | -| `POST` | `/api/knowledge/git-sources` | Owner only | Git Sources Connect | `pkg/dashboard/api.go:416` | -| `DELETE` | `/api/knowledge/git-sources` | Owner only | Git Sources Disconnect | `pkg/dashboard/api.go:417` | -| `POST` | `/api/knowledge/obsidian/sync` | Dashboard auth/session | Obsidian Sync | `pkg/dashboard/api.go:418` | -| `GET` | `/api/knowledge/documents` | Dashboard auth/session | Documents List | `pkg/dashboard/api.go:419` | -| `POST` | `/api/knowledge/documents` | Dashboard auth/session | Documents Import | `pkg/dashboard/api.go:420` | -| `GET` | `/api/knowledge/documents/{slug}` | Dashboard auth/session | Document Get | `pkg/dashboard/api.go:421` | -| `DELETE` | `/api/knowledge/documents/{slug}` | Dashboard auth/session | Document Delete | `pkg/dashboard/api.go:422` | -| `POST` | `/api/knowledge/documents/{slug}/reimport` | Dashboard auth/session | Document Reimport | `pkg/dashboard/api.go:423` | -| `GET` | `/api/knowledge/context7/search` | Dashboard auth/session | Context7 Search | `pkg/dashboard/api.go:424` | -| `POST` | `/api/knowledge/cleanup-orphans` | Dashboard auth/session | Cleanup Orphans | `pkg/dashboard/api.go:425` | -| `GET` | `/api/knowledge/channels` | Dashboard auth/session | Knowledge Channels List | `pkg/dashboard/api.go:388` | -| `POST` | `/api/knowledge/channels` | Dashboard auth/session | Knowledge Channel Create | `pkg/dashboard/api.go:389` | +| `GET` | `/api/knowledge/git-sources` | Dashboard auth/session | Git Sources List | `pkg/dashboard/api.go:416` | +| `POST` | `/api/knowledge/git-sources` | Owner only | Git Sources Connect | `pkg/dashboard/api.go:417` | +| `DELETE` | `/api/knowledge/git-sources` | Owner only | Git Sources Disconnect | `pkg/dashboard/api.go:418` | +| `POST` | `/api/knowledge/obsidian/sync` | Dashboard auth/session | Obsidian Sync | `pkg/dashboard/api.go:419` | +| `GET` | `/api/knowledge/documents` | Dashboard auth/session | Documents List | `pkg/dashboard/api.go:420` | +| `POST` | `/api/knowledge/documents` | Dashboard auth/session | Documents Import | `pkg/dashboard/api.go:421` | +| `GET` | `/api/knowledge/documents/{slug}` | Dashboard auth/session | Document Get | `pkg/dashboard/api.go:422` | +| `DELETE` | `/api/knowledge/documents/{slug}` | Dashboard auth/session | Document Delete | `pkg/dashboard/api.go:423` | +| `POST` | `/api/knowledge/documents/{slug}/reimport` | Dashboard auth/session | Document Reimport | `pkg/dashboard/api.go:424` | +| `GET` | `/api/knowledge/context7/search` | Dashboard auth/session | Context7 Search | `pkg/dashboard/api.go:425` | +| `POST` | `/api/knowledge/cleanup-orphans` | Dashboard auth/session | Cleanup Orphans | `pkg/dashboard/api.go:426` | +| `GET` | `/api/knowledge/channels` | Dashboard auth/session | Knowledge Channels List | `pkg/dashboard/api.go:389` | +| `POST` | `/api/knowledge/channels` | Dashboard auth/session | Knowledge Channel Create | `pkg/dashboard/api.go:390` | | `GET` | `/api/knowledge/connectors` | Dashboard auth/session | Knowledge connector statuses, each with a live `progress` block while a sync runs, and publish mirror status (`{"connectors": [...], "publish": {...}\|null}`, see [knowledge-connectors.md](../knowledge-connectors.md)) | `pkg/dashboard/api_knowledge_connectors.go:24` | | `POST` | `/api/knowledge/connectors/{name}/sync` | Owner only | Start one connector sync now (202; 404 unknown, 409 running) | `pkg/dashboard/api_knowledge_connectors.go:25` | | `POST` | `/api/knowledge/publish/sync` | Owner only | Run a publish mirror batch now (202 with publish status; 503 mirror not running, 409 batch in progress) | `pkg/dashboard/api_knowledge_connectors.go:26` | diff --git a/src/docs/api-reference/nous.md b/src/docs/api-reference/nous.md index 8bc04784e2..fb3331cf72 100644 --- a/src/docs/api-reference/nous.md +++ b/src/docs/api-reference/nous.md @@ -5,28 +5,28 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| -| `GET` | `/api/nous/status` | Dashboard auth/session | Nous Status — includes `experimentLoop` (`dir`, `lastWriteAt`, `running`, `idleAfterSeconds`): whether the external experiment loop, the only producer of proposals, has written under `/var/run/nous/governor` within 24 evaluation cycles; ready cards then carry `experimentLoopIdle` ([#12541](https://github.com/hivecommons/hive/issues/12541)) | `pkg/dashboard/api.go:461` | -| `GET` | `/api/nous/ledger` | Dashboard auth/session | Nous Ledger | `pkg/dashboard/api.go:462` | -| `GET` | `/api/nous/principles` | Dashboard auth/session | Nous Principles | `pkg/dashboard/api.go:463` | -| `POST` | `/api/nous/approve` | Owner only | Nous Approve | `pkg/dashboard/api.go:464` | -| `POST` | `/api/nous/abort` | Owner only | Nous Abort | `pkg/dashboard/api.go:465` | -| `PUT` | `/api/nous/mode` | Owner only | Nous Mode | `pkg/dashboard/api.go:466` | -| `PUT` | `/api/nous/scope` | Owner only | Nous Scope | `pkg/dashboard/api.go:467` | -| `GET` | `/api/nous/phase` | Dashboard auth/session | Nous Phase | `pkg/dashboard/api.go:468` | -| `PUT` | `/api/nous/gate-decision` | Owner only | Nous Gate Decision | `pkg/dashboard/api.go:469` | -| `GET` | `/api/nous/gate-pending` | Dashboard auth/session | Nous Gate Pending | `pkg/dashboard/api.go:470` | -| `POST` | `/api/nous/gate-respond` | Owner only | Nous Gate Respond | `pkg/dashboard/api.go:471` | -| `GET` | `/api/nous/gate-response` | Dashboard auth/session | Nous Gate Response | `pkg/dashboard/api.go:472` | -| `GET` | `/api/nous/config` | Dashboard auth/session | Nous Config Get | `pkg/dashboard/api.go:473` | -| `PUT` | `/api/nous/config/goals` | Owner only | Nous Config Goals — legacy; the dashboard no longer exposes the research question in the ⚙ dialog, use `PATCH /api/nous/campaigns/{id}` | `pkg/dashboard/api.go:474` | -| `PUT` | `/api/nous/config/repos` | Owner only | Nous Config Repos — the allow-list of repos experiments may target (empty = any) | `pkg/dashboard/api.go:475` | -| `PUT` | `/api/nous/config/output` | Owner only | Nous Config Output | `pkg/dashboard/api.go:476` | -| `PUT` | `/api/nous/config/fast-fail` | Owner only | Nous Config Fast Fail | `pkg/dashboard/api.go:477` | -| `PUT` | `/api/nous/config/schedule` | Owner only | Nous Config Schedule | `pkg/dashboard/api.go:478` | -| `PUT` | `/api/nous/config/controllables` | Owner only | Nous Config Controllables | `pkg/dashboard/api.go:479` | -| `PUT` | `/api/nous/config/principles` | Owner only | Nous Config Principles | `pkg/dashboard/api.go:480` | -| `DELETE` | `/api/nous/principles/{id}` | Owner only | Nous Delete Principle | `pkg/dashboard/api.go:481` | -| `POST` | `/api/nous/campaign/start` | Owner only | Nous Campaign Start — archives the active campaign and starts a new experiment whose baseline restarts at 0 ([#12501](https://github.com/hivecommons/hive/issues/12501)) | `pkg/dashboard/api.go:482` | -| `GET` | `/api/nous/campaigns` | Any | Nous Campaigns List — every experiment with its per-campaign baseline, scope, results and stage ([#12532](https://github.com/hivecommons/hive/issues/12532)) | `pkg/dashboard/api.go:483` | -| `POST` | `/api/nous/campaigns` | Owner only | Nous Campaigns Create — starts an experiment alongside the running ones; 409 `scope_conflict` when a running experiment shares a repo target or both are hive-wide ([#12532](https://github.com/hivecommons/hive/issues/12532)) | `pkg/dashboard/api.go:484` | -| `PATCH` | `/api/nous/campaigns/{id}` | Owner only | Nous Campaign Patch — pause / resume / archive, or edit question, hypothesis and scope. Hypothesis/tag edits save in place (`status: "updated"`); a changed question or repo set needs `restart: true` (else 409 `restart_required`) and archives the campaign as version N while creating version N+1 with `restartedFrom` (`status: "restarted", campaign, archived`); resume, scope widening and restarts re-run the conflict guard ([#12532](https://github.com/hivecommons/hive/issues/12532)) | `pkg/dashboard/api.go:485` | +| `GET` | `/api/nous/status` | Dashboard auth/session | Nous Status — includes `experimentLoop` (`dir`, `lastWriteAt`, `running`, `idleAfterSeconds`): whether the external experiment loop, the only producer of proposals, has written under `/var/run/nous/governor` within 24 evaluation cycles; ready cards then carry `experimentLoopIdle` ([#12541](https://github.com/hivecommons/hive/issues/12541)) | `pkg/dashboard/api.go:462` | +| `GET` | `/api/nous/ledger` | Dashboard auth/session | Nous Ledger | `pkg/dashboard/api.go:463` | +| `GET` | `/api/nous/principles` | Dashboard auth/session | Nous Principles | `pkg/dashboard/api.go:464` | +| `POST` | `/api/nous/approve` | Owner only | Nous Approve | `pkg/dashboard/api.go:465` | +| `POST` | `/api/nous/abort` | Owner only | Nous Abort | `pkg/dashboard/api.go:466` | +| `PUT` | `/api/nous/mode` | Owner only | Nous Mode | `pkg/dashboard/api.go:467` | +| `PUT` | `/api/nous/scope` | Owner only | Nous Scope | `pkg/dashboard/api.go:468` | +| `GET` | `/api/nous/phase` | Dashboard auth/session | Nous Phase | `pkg/dashboard/api.go:469` | +| `PUT` | `/api/nous/gate-decision` | Owner only | Nous Gate Decision | `pkg/dashboard/api.go:470` | +| `GET` | `/api/nous/gate-pending` | Dashboard auth/session | Nous Gate Pending | `pkg/dashboard/api.go:471` | +| `POST` | `/api/nous/gate-respond` | Owner only | Nous Gate Respond | `pkg/dashboard/api.go:472` | +| `GET` | `/api/nous/gate-response` | Dashboard auth/session | Nous Gate Response | `pkg/dashboard/api.go:473` | +| `GET` | `/api/nous/config` | Dashboard auth/session | Nous Config Get | `pkg/dashboard/api.go:474` | +| `PUT` | `/api/nous/config/goals` | Owner only | Nous Config Goals — legacy; the dashboard no longer exposes the research question in the ⚙ dialog, use `PATCH /api/nous/campaigns/{id}` | `pkg/dashboard/api.go:475` | +| `PUT` | `/api/nous/config/repos` | Owner only | Nous Config Repos — the allow-list of repos experiments may target (empty = any) | `pkg/dashboard/api.go:476` | +| `PUT` | `/api/nous/config/output` | Owner only | Nous Config Output | `pkg/dashboard/api.go:477` | +| `PUT` | `/api/nous/config/fast-fail` | Owner only | Nous Config Fast Fail | `pkg/dashboard/api.go:478` | +| `PUT` | `/api/nous/config/schedule` | Owner only | Nous Config Schedule | `pkg/dashboard/api.go:479` | +| `PUT` | `/api/nous/config/controllables` | Owner only | Nous Config Controllables | `pkg/dashboard/api.go:480` | +| `PUT` | `/api/nous/config/principles` | Owner only | Nous Config Principles | `pkg/dashboard/api.go:481` | +| `DELETE` | `/api/nous/principles/{id}` | Owner only | Nous Delete Principle | `pkg/dashboard/api.go:482` | +| `POST` | `/api/nous/campaign/start` | Owner only | Nous Campaign Start — archives the active campaign and starts a new experiment whose baseline restarts at 0 ([#12501](https://github.com/hivecommons/hive/issues/12501)) | `pkg/dashboard/api.go:483` | +| `GET` | `/api/nous/campaigns` | Any | Nous Campaigns List — every experiment with its per-campaign baseline, scope, results and stage ([#12532](https://github.com/hivecommons/hive/issues/12532)) | `pkg/dashboard/api.go:484` | +| `POST` | `/api/nous/campaigns` | Owner only | Nous Campaigns Create — starts an experiment alongside the running ones; 409 `scope_conflict` when a running experiment shares a repo target or both are hive-wide ([#12532](https://github.com/hivecommons/hive/issues/12532)) | `pkg/dashboard/api.go:485` | +| `PATCH` | `/api/nous/campaigns/{id}` | Owner only | Nous Campaign Patch — pause / resume / archive, or edit question, hypothesis and scope. Hypothesis/tag edits save in place (`status: "updated"`); a changed question or repo set needs `restart: true` (else 409 `restart_required`) and archives the campaign as version N while creating version N+1 with `restartedFrom` (`status: "restarted", campaign, archived`); resume, scope widening and restarts re-run the conflict guard ([#12532](https://github.com/hivecommons/hive/issues/12532)) | `pkg/dashboard/api.go:486` | diff --git a/src/docs/api-reference/packs-and-acmm.md b/src/docs/api-reference/packs-and-acmm.md index 5777595c83..6c34ce84e1 100644 --- a/src/docs/api-reference/packs-and-acmm.md +++ b/src/docs/api-reference/packs-and-acmm.md @@ -17,17 +17,18 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/repos/{owner}/{repo}/hold-permission` | Dashboard auth/session | Reports whether the signed-in user can toggle hold chips for a repository card. Owners are allowed; otherwise the server checks GitHub `repos/{owner}/{repo}/collaborators/{user}/permission` and briefly caches the effective permission | `pkg/dashboard/api.go:327`, `pkg/dashboard/api_repo_hold.go` | | `GET` | `/api/repos/{owner}/{repo}/items/{number}` | Dashboard session | Per-item detail for the activity monitor's decision badge: `{repo, number, stage, stage_slug, operator_actions[], operator_action_count, last_operator_action}`. `operator_actions[]` is the server-side ledger of every row action submitted from the dashboard (hold/release, decision, decide-delegated, send-to-human, accept-triage — recorded by `recordOperatorAction` around those routes) as `{action, actor, at, note, target, outcome: pending|applied|no-op|failed, detail, head_sha, stage}`; `last_operator_action` adds the derived `state` (`waiting|addressed|stuck|pending|failed`), `stuck_after_seconds` and `followed[]` (the stage hops after the action). The same `last_operator_action` / `operator_action_count` ride every stage-tracker row and linked PR. Persisted in `/data/operator-actions.json`; `HIVE_OPERATOR_ACTION_STUCK_AFTER` (default `30m`) sets the stuck window. Rows also carry `rebase_merge: {state: approved|rebasing|ci-pending|merged|failed, actor, base, text, fail_reason, conflict_files[], armed_at}` while a *Rebase, then merge as maintainer* follow-through is live or just settled (persisted in `/data/rebase-merge-followups.json`; `fail_reason: foreign-head` when the head moved after the approval by someone other than the hive, so nothing merged), and `rebase: {attempt, max, exhausted, head, text}` on a conflicting PR the fixer is rebasing under the two-attempt loop guard (`/data/rebase-attempts.json`). | `pkg/dashboard/api.go`, `pkg/dashboard/operator_actions.go` | | `POST` | `/api/repos/{owner}/{repo}/items/{number}/hold` | Owner or repo write/maintain/admin | Add or remove a dashboard hold chip for an issue or PR. Body `{"held": true}` adds the hive's exact-match canonical `hive-pause/` label (shortened with a hash suffix when the plain spelling would exceed GitHub's 50-character label cap, [#17037](https://github.com/hivecommons/hive/issues/17037)); `{"held": false}` removes exactly the labels causing the hold (`hive-pause/` and/or generic hold labels) and never removes `hive/` provenance. A GitHub failure answers `424` with the step and GitHub's reason — never `502`/`503`, which the hosted Ingress replaces with its generic "hive unavailable" page. Every toggle writes an audit-log entry; the #8851 upgrade migration writes `/data/hive-hold-migration-.json` with audit-backed, provenance-only, and ambiguous legacy `hive/` classifications. | `pkg/dashboard/api.go:331`, `pkg/dashboard/api_repo_hold.go` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decision` | Owner or repo write/maintain/admin, signed-in GitHub user | Record an operator decision from the activity monitor's row menu / selection bar. Body `{"decision": "approve"|"direction"|"close-superseded"|"close-wontfix"|"close-read"|"close-issue"|"adopt"|"reroute"|"re-author"|"merge-now"|"queue-merge", "comment": "…", "type": "issue"|"pr", "superseded_by": "#458", "force": true, "to": ""|"any"}` (`force` only with `adopt`, `to` only with `reroute`; an unknown `decision` is a 400). On an issue parked at 045, `approve`/`direction` act exactly as a maintainer's `/hive approve` / `/hive decision ` comment would (labels, `approved-direction`, stage-engine Unparked fact, reply comment naming the operator). On a PR parked at 085 (`type: "pr"`), `approve` posts the `/lgtm` and `/approve` commands as two comments attributed to the operator, records the approval against the head as the human answer to a `requires_human` / decision-requested verdict (the lanes and the stage engine honour it like a trusted merger's Approve review), lifts `needs-human`, clears the sentinel label and acknowledges the bundle's sentinel findings for that head, re-derives the stage and drops the tracker cache — the response adds `released` (`approval-recorded`, `needs-human`, `sentinel-label`, `sentinel-acknowledged`) and `stage`; the merge gate decides from there (no review as the operator, no merge) — and `direction` records the text as a human change request against the head — the `/hive decision` fix lane — on a hive-authored PR, and on a contributor's clanker PR (`author/clanker` / hive attribution markers) where the text is posted to the contributor's hive and the PR moves to `stage/072-returned-to-contributor` (`status: "direction-returned-to-contributor"`); a person's PR, which no hive can carry direction to, answers 409. The close variants first post a required comment naming the operator (and the superseding PR when `superseded_by` is given); a failed comment prevents closure. `close-superseded` and `close-wontfix` close as **not planned**; `close-read` acknowledges an advisory issue and closes it **as completed**. `close-issue` (`type: "issue"` only) closes the single named open issue **as completed**, at any stage, leaving linked PRs and other issues untouched; it returns 400 for a PR (including one sent as an issue), 404 when the issue is not found, and 409 when already closed. It retains the existing permission and mutation gates, including the paused-repo `status: "refused"` result without writes. `adopt` and `re-author` require `type: "pr"` and queue adoption via the `adoption/supersede` label (409 unless `governor.labels.stage.adoption` is enabled). `adopt` with `"force": true` is *Adopt now* ([#15038](https://github.com/hivecommons/hive/issues/15038)): it bypasses the author's presence, the grace window and `maintainer_policy`, marks the stage record and nudges the automerge sweep so the adoption engine supersedes the head at once (responds `status: "already-adopted"` when nothing is left to do; 400 on the hive's own PR). `reroute` (`type: "pr"`, `"to": ""|"any"`) hands the PR's follow-up work to another online clanker through the contributor fix queue, posts a `` note and arms a pickup timer that falls back to Adopt now after `governor.reroute.pickup_timeout`; answers `status: "rerouted"`, 409 when no clanker is online or adoption is disabled. On a PR at 090, `queue-merge` (*Approve and let hive merge*, the lead action) records an approval attributed to the operator and applies the automerge label, returning `status: "queued-for-merge"` (on the hive's own PR, which the App cannot review, the queue note is a comment and the operator's approval is recorded as `approve` records it — `released` lists `approval-recorded`, `admitted`); hive's merge sweep merges on its next tick once CI is green and the head has soaked, and that recorded operator approval is the one thing that lets the sweep merge an untrusted-author PR (the merge comment names the operator). `merge-now` (*Merge now as maintainer*, secondary) posts an attributed comment and merges immediately through the hive's GitHub App, returning `status: "merged"`. Both require `type: "pr"` and a verified owner or `merger` role in addition to the route's repo permission check; both refuse closed/merged PRs and the operator's own PR. `merge-now` on a PR whose `mergeable_state` is `dirty`/`behind` instead answers `202` with `status: "rebase-queued"` (approval recorded, rebase kicked, merge follows via the follow-through once the hive's own rebase is green; a head pushed by anyone else fails the follow-through closed; `head-not-pushable` refusal on a fork without maintainer edits). `approve` on such a PR adds `rebase: {attempt, max, exhausted, head, text}` for the rebase episode it opened. Every decision writes an audit-log entry (`repo_item_decision_*`, e.g. `repo_item_decision_adopt_now`, `repo_item_decision_reroute`). | `pkg/dashboard/api.go:332`, `pkg/dashboard/api_repo_item_decision.go` | -| `GET` | `/api/notes` | Signed-in GitHub user (or verified owner) | Maintainer notes — the private per-item notes maintainers leave each other on Activity Monitor rows ([#maintainer-notes](../operator-reference.md#maintainer-notes)). `?repo=owner/name&number=N` lists one item's live notes oldest first; with no query, every live note in the hive (the SPA's count badges). `{notes: [{id, repo, number, author, text, created_at}]}`. Never read from or written to GitHub. | `pkg/dashboard/api.go:336`, `pkg/dashboard/api_maintainer_notes.go` | -| `POST` | `/api/notes` | Owner or repo write/maintain/admin, signed-in GitHub user | Append a maintainer note. Body `{repo, number, text}` — `text` is plain text up to 2000 characters; the author is the dashboard session's GitHub login, never a body field. `401` signed out, `403` without write on the repo, `400` for an empty/oversized note or a bad item. `201 {ok, note}`; appended to `/data/maintainer-notes.jsonl`, audited as `maintainer_note_add`, and broadcast as the `maintainer-notes` SSE event `{seq, repo, number, count, action}` so other maintainers' browsers refresh the row. | `pkg/dashboard/api.go:337`, `pkg/dashboard/api_maintainer_notes.go` | -| `DELETE` | `/api/notes/{id}` | The note's author, or a verified owner | Tombstone a maintainer note (append-only store: a `deleted_at` record, never a rewrite). `404` unknown or already deleted, `403` for anyone else. `{ok, note}`; audited as `maintainer_note_delete`, broadcast as `maintainer-notes`. | `pkg/dashboard/api.go:338`, `pkg/dashboard/api_maintainer_notes.go` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decision` | Owner or repo write/maintain/admin, signed-in GitHub user | Record an operator decision from the activity monitor's row menu / selection bar. Body `{"decision": "approve"|"direction"|"close-superseded"|"close-wontfix"|"close-read"|"close-issue"|"adopt"|"reroute"|"re-author"|"merge-now"|"queue-merge", "comment": "…", "type": "issue"|"pr", "superseded_by": "#458", "force": true, "to": ""|"any"}` (`force` only with `adopt`, `to` only with `reroute`; an unknown `decision` is a 400). On an issue parked at 045, `approve`/`direction` act exactly as a maintainer's `/hive approve` / `/hive decision ` comment would (labels, `approved-direction`, stage-engine Unparked fact, reply comment naming the operator). On a PR parked at 085 (`type: "pr"`), `approve` posts the `/lgtm` and `/approve` commands as two comments attributed to the operator, records the approval against the head as the human answer to a `requires_human` / decision-requested verdict (the lanes and the stage engine honour it like a trusted merger's Approve review), lifts `needs-human`, clears the sentinel label and acknowledges the bundle's sentinel findings for that head, re-derives the stage and drops the tracker cache — the response adds `released` (`approval-recorded`, `needs-human`, `sentinel-label`, `sentinel-acknowledged`) and `stage`; the merge gate decides from there (no review as the operator, no merge) — and `direction` records the text as a human change request against the head — the `/hive decision` fix lane — on a hive-authored PR, and on a contributor's clanker PR (`author/clanker` / hive attribution markers) where the text is posted to the contributor's hive and the PR moves to `stage/072-returned-to-contributor` (`status: "direction-returned-to-contributor"`); a person's PR, which no hive can carry direction to, answers 409. The close variants first post a required comment naming the operator (and the superseding PR when `superseded_by` is given); a failed comment prevents closure. `close-superseded` and `close-wontfix` close as **not planned**; `close-read` acknowledges an advisory issue and closes it **as completed**. `close-issue` (`type: "issue"` only) closes the single named open issue **as completed**, at any stage, leaving linked PRs and other issues untouched; it returns 400 for a PR (including one sent as an issue), 404 when the issue is not found, and 409 when already closed. It retains the existing permission and mutation gates, including the paused-repo `status: "refused"` result without writes. `adopt` and `re-author` require `type: "pr"` and queue adoption via the `adoption/supersede` label (409 unless `governor.labels.stage.adoption` is enabled). `adopt` with `"force": true` is *Adopt now* ([#15038](https://github.com/hivecommons/hive/issues/15038)): it bypasses the author's presence, the grace window and `maintainer_policy`, marks the stage record and nudges the automerge sweep so the adoption engine supersedes the head at once (responds `status: "already-adopted"` when nothing is left to do; 400 on the hive's own PR). `reroute` (`type: "pr"`, `"to": ""|"any"`) hands the PR's follow-up work to another online clanker through the contributor fix queue, posts a `` note and arms a pickup timer that falls back to Adopt now after `governor.reroute.pickup_timeout`; answers `status: "rerouted"`, 409 when no clanker is online or adoption is disabled. On a PR at 090, `queue-merge` (*Approve and let hive merge*, the lead action) records an approval attributed to the operator and applies the automerge label, returning `status: "queued-for-merge"` (on the hive's own PR, which the App cannot review, the queue note is a comment and the operator's approval is recorded as `approve` records it — `released` lists `approval-recorded`, `admitted`); hive's merge sweep merges on its next tick once CI is green and the head has soaked, and that recorded operator approval is the one thing that lets the sweep merge an untrusted-author PR (the merge comment names the operator). `merge-now` (*Merge now as maintainer*, secondary) posts an attributed comment and merges immediately through the hive's GitHub App, returning `status: "merged"`. Both require `type: "pr"` and a verified owner or `merger` role in addition to the route's repo permission check; both refuse closed/merged PRs and the operator's own PR. `merge-now` on a PR whose `mergeable_state` is `dirty`/`behind` instead answers `202` with `status: "rebase-queued"` (approval recorded, rebase kicked, merge follows via the follow-through once the hive's own rebase is green; a head pushed by anyone else fails the follow-through closed; `head-not-pushable` refusal on a fork without maintainer edits). `approve` on such a PR adds `rebase: {attempt, max, exhausted, head, text}` for the rebase episode it opened. Every decision writes an audit-log entry (`repo_item_decision_*`, e.g. `repo_item_decision_adopt_now`, `repo_item_decision_reroute`). | `pkg/dashboard/api.go:333`, `pkg/dashboard/api_repo_item_decision.go` | +| `GET` | `/api/notes` | Signed-in GitHub user (or verified owner) | Maintainer notes — the private per-item notes maintainers leave each other on Activity Monitor rows ([#maintainer-notes](../operator-reference.md#maintainer-notes)). `?repo=owner/name&number=N` lists one item's live notes oldest first; with no query, every live note in the hive (the SPA's count badges). `{notes: [{id, repo, number, author, text, created_at}]}`. Never read from or written to GitHub. | `pkg/dashboard/api.go:337`, `pkg/dashboard/api_maintainer_notes.go` | +| `POST` | `/api/notes` | Owner or repo write/maintain/admin, signed-in GitHub user | Append a maintainer note. Body `{repo, number, text}` — `text` is plain text up to 2000 characters; the author is the dashboard session's GitHub login, never a body field. `401` signed out, `403` without write on the repo, `400` for an empty/oversized note or a bad item. `201 {ok, note}`; appended to `/data/maintainer-notes.jsonl`, audited as `maintainer_note_add`, and broadcast as the `maintainer-notes` SSE event `{seq, repo, number, count, action}` so other maintainers' browsers refresh the row. | `pkg/dashboard/api.go:338`, `pkg/dashboard/api_maintainer_notes.go` | +| `DELETE` | `/api/notes/{id}` | The note's author, or a verified owner | Tombstone a maintainer note (append-only store: a `deleted_at` record, never a rewrite). `404` unknown or already deleted, `403` for anyone else. `{ok, note}`; audited as `maintainer_note_delete`, broadcast as `maintainer-notes`. | `pkg/dashboard/api.go:339`, `pkg/dashboard/api_maintainer_notes.go` | | `POST` / `GET` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated` | Same as `…/hold` (owner or repo write), signed-in GitHub user; `decisions.delegate.enabled` (403 when off) | *Let hive decide*: enqueue a delegated-decision job in which the hive decides the parked item itself as the owner's delegate under `pkg/delegatedecision.PolicyText` and records it as a human decision (`/hive decision` comment with the `` marker, park labels off, `triage/accepted`, queue approval on a PR head). Body `{"type": "issue"|"pr", "reason", "caption", "sentinel_reason"}`. `POST` answers 202 with the job (`{id, status: "running"|"done"|"failed", decision: {verdict, rule, text, rationale, actions, keeps_park, ladder?: {decision, reason, ruled_out[]}}, notes, error}`; `ladder` is set on contributor-PR decisions and names the rung that decided — `already-fixed` → `mergeable-as-is` → `rebase-then-merge` → `return-to-contributor` → `contributor-offline` — and why each rung above it did not apply); 409 with the running job while one is in flight; `GET` reads it. Rails: never merges, refuses items wearing `hold`, never grants secrets/permissions (`needs-owner` + `hold` instead), recommends only on hive policy/governance questions (keeps 085), and never decides a PR whose CI is running or whose review is incomplete on the current head — it answers `no-effect` (rule `mid-flight`, nothing written; fails closed, "review state not yet loaded", when the PR's review state cannot be read from the tracker; per PR in the `prs` fan-out, where the PR is skipped and counted as such), and the policy itself never releases (`default-release`, `small-low-risk`) a head whose checks are pending (rule `ci-pending`). Audited as `repo_item_decision_delegated[_failed]`. See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:329`, `pkg/dashboard/api_repo_item_decide_delegated.go` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated/plan` | Same as `…/decide-delegated` | Preview for *Let hive decide*: runs the same owner-delegate policy with **no side effects** (nothing written, no job) and answers `{would, rule, acting, title, summary, why, consequences[], ladder, mergeable_as_is, alternatives[], writes: false, prior, notes}` — `summary` is one verb-first sentence with no "Hive would:" prefix (*Send #15332 back to its author with one instruction: make CI green, nothing else.*), `why` one short line (*CI is red.*), `consequences` at most two items, `ladder` the rung that decided with its `ruled_out` list, and `mergeable_as_is` whether an as-is merge is honest (the queue-merge and merge-now alternatives are dropped when it is not). The dialog shows **Cancel** / **Let hive do that**, plus **Approve and let hive merge** (or **Merge now as maintainer** when the hive would approve anyway) only when `mergeable_as_is`; only then does the SPA post `…/decide-delegated` with `chosen` naming the button. A transient GitHub failure (5xx, rate limit, timeout) is retried twice with backoff before the plan gives up. A failure answers `{ok: false, error, reason, retryable, attempts, elapsed_ms, hive, hint}` under **409** when the item is no longer open (`reason: not-open`) or **424** when a read it depends on failed (`github`), is not configured (`config`) or the plan itself failed (`plan`) — never 502/503, which the hosted Ingress intercepts and replaces with its generic *hive unavailable* page (hivecommons/hive#16776). See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:341`, `pkg/dashboard/api_repo_item_decide_delegated_plan.go` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/recheck` | Same as `…/hold` (owner or repo write), signed-in GitHub user | *Re-check permissions* on an issue parked on a capability blocker (#15099): probes the GitHub App installation's permissions; when the missing permission is granted, clears every ledger entry blocked on it and un-parks the item (`{result: {outcome: "released", …}}`), otherwise `{result: {outcome: "no-effect", reason: "blocker", options: [...]}}`; 404 when the item has no blocker, 409 when the blocker is not a capability gap | `pkg/dashboard/api.go:342` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/close-partial` | Same as `…/hold` (owner or repo write), signed-in GitHub user | Option (c) on a capability blocker (#15099): labels the issue `hive/partially-addressed`, posts the operator's `{"comment"}` naming what remains and closes it; the ledger entry is cleared | `pkg/dashboard/api.go:343` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/accept-triage` | Owner or repo write/maintain/admin | Accept triage on an issue from the activity monitor's row menu — what a maintainer accepting triage on GitHub does by hand: adds the reporter-trust triage label (`triage/accepted`, or the first of `issue_filter.reporter_trust.untrusted_require_labels`; the label is created in the repo if missing) and removes the awaiting label (`needs-triage` / `reporter_trust.awaiting_label`) and a Hive-written `stage/015-triage-needed`. Empty body. Returns `{ok, repo, number, acceptLabel, added, removed, alreadyAccepted, minStatusSeq}`; an issue already carrying the accept label with nothing left to remove is a no-op (`alreadyAccepted: true`, no write, no audit). 404 for a pull request or an unknown item. The status snapshot's labels are patched so the next reconcile reads 010 Actionable before the engine's own 015 → 010 derivation. Every write is audited as `repo_item_accept_triage` under the dashboard user. | `pkg/dashboard/api.go:554`, `pkg/dashboard/api_repo_item_accept_triage.go` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/sentinel-confirm` | Owner or repo write/maintain/admin | **Confirm safe** on the activity monitor's human-gate pill ([#17470](https://github.com/hivecommons/hive/issues/17470)): a person confirms a sentinel finding is intended. Body `{comment?, type?}` (`type` is `pr` or `issue`, comment ≤ 4000 characters). Posts the confirmation as a comment first — ``, `@user confirmed the sentinel finding safe from the dashboard.`, then the comment text — and removes every label matching the configured sentinel label (`sentinel.label`, default `sentinel-alert`, case-insensitive). Returns `{ok, repo, number, label, removed, alreadyClear, result}`; with no sentinel label on the item the comment is still posted and `alreadyClear` is true. 403 for a repository the hive does not watch. Audited as `repo_item_sentinel_confirm` under the dashboard user; the operator-action ledger records it as `confirm-sentinel`. | `pkg/dashboard/api.go:333`, `pkg/dashboard/api_repo_item_sentinel_confirm.go` | -| `GET` | `/api/acmm/evaluation` | Dashboard auth/session | ACMMEvaluation — combined codebase + operational result, cached server-side for 1 hour (`acmmEvalTTL`). `?refresh=1` (the dashboard's "🔄 Re-evaluate" button, #5877) bypasses the hourly TTL but is debounced server-side: requests within 1 minute of the last evaluation (`acmmRefreshDebounce`) still serve the cache, since a full refresh costs up to ~29 GitHub GetContents calls per repo. The response's `last_evaluated_at` timestamp reports when the cached evaluation was computed | `pkg/dashboard/api.go:345`, `pkg/dashboard/api_acmm_eval.go` | -| `POST` | `/api/acmm/issue` | Owner only | ACMMCreate Issue — files on GitHub or, with `governor.acmm.issue_tracker: work_source` / body `tracker: "work_source"` on a Linear-sourced hive, on Linear; response `tracker` says which. See [ACMM policy matrix](../acmm-policy-matrix.md#where-acmm-gap-issues-are-filed) | `pkg/dashboard/api.go:346` | -| `GET` | `/api/acmm-recommendation` | Dashboard auth/session | Advisory level-up recommendation (`acmmadvisor.Recommendation`, JSON): never changes the applied level — see [ACMM advisor](../acmm-advisor.md) | `pkg/dashboard/api.go:347` | -| `GET` | `/api/hive-advice` | Dashboard auth/session | Weekly owner advice (`hiveadvisor.Result`, JSON) shared with the advisory digest: recommendations with `items`, `links` (Overview export paths) and `bands`; `bands[]` rule text; `counts` naming the governor actionable queue vs. the Overview total. Which recommendations show is frozen for 7 days; their numbers refresh every call — see [Owner advice](../advisory.md#owner-advice) | `pkg/dashboard/api.go:349`, `pkg/dashboard/api_hive_advice.go` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated/plan` | Same as `…/decide-delegated` | Preview for *Let hive decide*: runs the same owner-delegate policy with **no side effects** (nothing written, no job) and answers `{would, rule, acting, title, summary, why, consequences[], ladder, mergeable_as_is, alternatives[], writes: false, prior, notes}` — `summary` is one verb-first sentence with no "Hive would:" prefix (*Send #15332 back to its author with one instruction: make CI green, nothing else.*), `why` one short line (*CI is red.*), `consequences` at most two items, `ladder` the rung that decided with its `ruled_out` list, and `mergeable_as_is` whether an as-is merge is honest (the queue-merge and merge-now alternatives are dropped when it is not). The dialog shows **Cancel** / **Let hive do that**, plus **Approve and let hive merge** (or **Merge now as maintainer** when the hive would approve anyway) only when `mergeable_as_is`; only then does the SPA post `…/decide-delegated` with `chosen` naming the button. A transient GitHub failure (5xx, rate limit, timeout) is retried twice with backoff before the plan gives up. A failure answers `{ok: false, error, reason, retryable, attempts, elapsed_ms, hive, hint}` under **409** when the item is no longer open (`reason: not-open`) or **424** when a read it depends on failed (`github`), is not configured (`config`) or the plan itself failed (`plan`) — never 502/503, which the hosted Ingress intercepts and replaces with its generic *hive unavailable* page (hivecommons/hive#16776). See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:342`, `pkg/dashboard/api_repo_item_decide_delegated_plan.go` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/recheck` | Same as `…/hold` (owner or repo write), signed-in GitHub user | *Re-check permissions* on an issue parked on a capability blocker (#15099): probes the GitHub App installation's permissions; when the missing permission is granted, clears every ledger entry blocked on it and un-parks the item (`{result: {outcome: "released", …}}`), otherwise `{result: {outcome: "no-effect", reason: "blocker", options: [...]}}`; 404 when the item has no blocker, 409 when the blocker is not a capability gap | `pkg/dashboard/api.go:343` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/close-partial` | Same as `…/hold` (owner or repo write), signed-in GitHub user | Option (c) on a capability blocker (#15099): labels the issue `hive/partially-addressed`, posts the operator's `{"comment"}` naming what remains and closes it; the ledger entry is cleared | `pkg/dashboard/api.go:344` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/accept-triage` | Owner or repo write/maintain/admin | Accept triage on an issue from the activity monitor's row menu — what a maintainer accepting triage on GitHub does by hand: adds the reporter-trust triage label (`triage/accepted`, or the first of `issue_filter.reporter_trust.untrusted_require_labels`; the label is created in the repo if missing) and removes the awaiting label (`needs-triage` / `reporter_trust.awaiting_label`) and a Hive-written `stage/015-triage-needed`. Empty body. Returns `{ok, repo, number, acceptLabel, added, removed, alreadyAccepted, minStatusSeq}`; an issue already carrying the accept label with nothing left to remove is a no-op (`alreadyAccepted: true`, no write, no audit). 404 for a pull request or an unknown item. The status snapshot's labels are patched so the next reconcile reads 010 Actionable before the engine's own 015 → 010 derivation. Every write is audited as `repo_item_accept_triage` under the dashboard user. | `pkg/dashboard/api.go:555`, `pkg/dashboard/api_repo_item_accept_triage.go` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/sha-waiver` | Owner or repo write/maintain/admin | Waive or restore the SHA-hold requirement on an issue from the activity monitor's row menu. Body `{"waived": true\|false}`. Waiving adds the persistent `sha-waived` label (created if missing), removes `needs-sha` at once and posts one App-authored comment with a `` marker; restoring removes `sha-waived`. A repeat is a no-op; pull requests are 404. Returns `{ok, repo, number, waived, added, removed, minStatusSeq, result}`. Audited as `repo_item_sha_waiver`. | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/sentinel-confirm` | Owner or repo write/maintain/admin | **Confirm safe** on the activity monitor's human-gate pill ([#17470](https://github.com/hivecommons/hive/issues/17470)): a person confirms a sentinel finding is intended. Body `{comment?, type?}` (`type` is `pr` or `issue`, comment ≤ 4000 characters). Posts the confirmation as a comment first — ``, `@user confirmed the sentinel finding safe from the dashboard.`, then the comment text — and removes every label matching the configured sentinel label (`sentinel.label`, default `sentinel-alert`, case-insensitive). Returns `{ok, repo, number, label, removed, alreadyClear, result}`; with no sentinel label on the item the comment is still posted and `alreadyClear` is true. 403 for a repository the hive does not watch. Audited as `repo_item_sentinel_confirm` under the dashboard user; the operator-action ledger records it as `confirm-sentinel`. | `pkg/dashboard/api.go:334`, `pkg/dashboard/api_repo_item_sentinel_confirm.go` | +| `GET` | `/api/acmm/evaluation` | Dashboard auth/session | ACMMEvaluation — combined codebase + operational result, cached server-side for 1 hour (`acmmEvalTTL`). `?refresh=1` (the dashboard's "🔄 Re-evaluate" button, #5877) bypasses the hourly TTL but is debounced server-side: requests within 1 minute of the last evaluation (`acmmRefreshDebounce`) still serve the cache, since a full refresh costs up to ~29 GitHub GetContents calls per repo. The response's `last_evaluated_at` timestamp reports when the cached evaluation was computed | `pkg/dashboard/api.go:346`, `pkg/dashboard/api_acmm_eval.go` | +| `POST` | `/api/acmm/issue` | Owner only | ACMMCreate Issue — files on GitHub or, with `governor.acmm.issue_tracker: work_source` / body `tracker: "work_source"` on a Linear-sourced hive, on Linear; response `tracker` says which. See [ACMM policy matrix](../acmm-policy-matrix.md#where-acmm-gap-issues-are-filed) | `pkg/dashboard/api.go:347` | +| `GET` | `/api/acmm-recommendation` | Dashboard auth/session | Advisory level-up recommendation (`acmmadvisor.Recommendation`, JSON): never changes the applied level — see [ACMM advisor](../acmm-advisor.md) | `pkg/dashboard/api.go:348` | +| `GET` | `/api/hive-advice` | Dashboard auth/session | Weekly owner advice (`hiveadvisor.Result`, JSON) shared with the advisory digest: recommendations with `items`, `links` (Overview export paths) and `bands`; `bands[]` rule text; `counts` naming the governor actionable queue vs. the Overview total. Which recommendations show is frozen for 7 days; their numbers refresh every call — see [Owner advice](../advisory.md#owner-advice) | `pkg/dashboard/api.go:350`, `pkg/dashboard/api_hive_advice.go` | diff --git a/src/docs/dashboard-sections/activity-monitor.md b/src/docs/dashboard-sections/activity-monitor.md index 26f748d2fd..bc57a90865 100644 --- a/src/docs/dashboard-sections/activity-monitor.md +++ b/src/docs/dashboard-sections/activity-monitor.md @@ -549,6 +549,10 @@ For a parked issue, *Decide…* offers *Approve direction* (records the same `/h Entries you may not use are greyed with the reason in their tooltip, never hidden. Confirmation and free-text input use the dashboard's own dialogs — no browser prompts. Every action is an existing audited dashboard endpoint (the decision endpoint is `POST /api/repos/{owner}/{repo}/items/{number}/decision` and triage acceptance is `POST /api/repos/{owner}/{repo}/items/{number}/accept-triage`, see [api-reference.md](../api-reference.md)); none of them bypasses the hive's governance or merges anything. +#### SHA-held issues + +An issue held by the SHA-hold gate (`needs-sha`) is out of every agent lane, so its row used to read only "Open · since 11h". It now wears the pill *Held: needs commit SHA* (hover: "Post a commit SHA in the issue, or waive this requirement.") and the lit Open chevron carries the note *held: post a commit SHA* (#18866). The row's ⋯ menu offers *Waive SHA requirement* to the roles that can release a `hold` (the verified owner role, or write permission on the repo; greyed with the reason for anyone else). Once waived the pill reads *SHA waived by * and the menu item flips to *Restore SHA requirement*. See `sha-waived` in the labels reference. A `hold` keeps its own pill. + #### What a row tells you without a click (`tracker-cues`) The owner's framing (2026-10-28): "Hive is doing the right things mostly; we now need to keep the user informed of it — like a video game they can watch and see what happens easily." Every row therefore reads, in this order, *where it is → whether work is happening on it → what it waits on → what just happened*, with at most three cue types drawing the eye and nothing else blinking. diff --git a/src/docs/labels-and-control-signals/glossary-and-operations.md b/src/docs/labels-and-control-signals/glossary-and-operations.md index 125e4f8b82..48fc0c860f 100644 --- a/src/docs/labels-and-control-signals/glossary-and-operations.md +++ b/src/docs/labels-and-control-signals/glossary-and-operations.md @@ -136,7 +136,7 @@ Some sweeps list items themselves. They still use the same hold predicate (`Clie - Auto-merge sweeps use `Transport.IsHeldLabels`. The queued (`lgtm`) sweep skips a held PR before fetching it; the self-authored sweep skips held PRs and `needs-human` before merge (`src/pkg/github/automerge/automerge_sweep.go:23-38`, `src/pkg/github/automerge/automerge_sweep.go:954-959`, `src/pkg/github/automerge/automerge_sweep_loop.go:13-48`, `src/pkg/github/automerge/automerge_sweep_loop.go:73-92`). - The task-list sweep skips held issues before its exempt / issue `needs-human` gate. It does not comment on, relabel or close them (`src/pkg/github/task_list_sweep.go:848-854`). -- The SHA-hold sweep lists primary-repo `kind/bug` issues itself. Without a SHA it adds `issues.sha_hold_trusted_label` (default `needs-sha`) and a marker notice for every reporter; it never applies `hold`, and `needs-sha` keeps agents off the issue until it is removed (#18468; before that, untrusted reporters got literal `hold`, #12002). It removes only its own current hold: the newest label event must be a `labeled` by the App bot with an App-authored SHA-hold notice at or after it (`EnforceSHAHold` / `shaHoldIsOwn` in `src/pkg/github/client.go`). +- The SHA-hold sweep lists primary-repo `kind/bug` issues itself. Issues by the hive's own accounts, owners/maintainers (`reporter_trust.trusted_associations`), issues whose body names concrete repo file paths (self-attested: the path is never checked to exist, so a reporter can write one to skip the gate), and issues a maintainer waived with `sha-waived` are exempt (#18866), and an exempt issue's `needs-sha` is lifted on the next sweep. For everyone else, without a SHA it adds `issues.sha_hold_trusted_label` (default `needs-sha`) and a marker notice for every reporter; it never applies `hold`, and `needs-sha` keeps agents off the issue until it is removed (#18468; before that, untrusted reporters got literal `hold`, #12002). It removes only its own current hold: the newest label event must be a `labeled` by the App bot with an App-authored SHA-hold notice at or after it (`EnforceSHAHold` / `shaHoldIsOwn` in `src/pkg/github/client.go`). - PR-request watching applies server-side holds after creation; the wrapper discards an agent's `--label hold` (`src/pkg/github/pr_request_watcher.go:452-524`, `bin/hive-open-pr.sh:142-150`). Policy templates also say to respect `hold`, `on-hold`, `hold/review`, `hive-pause/`, any label containing `hold`, and exempt `do-not-merge`. That instruction is a prompt-level backstop; enumeration and sweep checks are the hard enforcement. diff --git a/src/docs/labels-and-control-signals/reference.md b/src/docs/labels-and-control-signals/reference.md index e76636ea44..ce0cd77f97 100644 --- a/src/docs/labels-and-control-signals/reference.md +++ b/src/docs/labels-and-control-signals/reference.md @@ -207,15 +207,39 @@ The hard-suppress reconcile also lifts this `hold` once a PR referencing the iss **Applies to:** Issues. **Kind:** Hard (issue gate; not a PR merge gate). -A `kind/bug` without a SHA gets this label plus the `` notice. While it is on the issue no agent implements, decomposes or claims it, whatever the reporter-trust setting; the issue shows as filtered in the work list. The sweep removes it once a SHA appears, which releases the issue. Description: "Waiting on the reporter for the commit SHA; hive won't work this until it's added." +A primary-repo `kind/bug` filed by an outside reporter without a SHA gets this label plus the `` notice. While it is on the issue no agent implements, decomposes or claims it, whatever the reporter-trust setting; the issue shows as filtered in the work list and never reaches the Actionable stage. The sweep removes it once a SHA appears, which releases the issue. Description: "Waiting on the reporter for the commit SHA; hive won't work this until it's added." + +**Exempt from the gate** ([#18866](https://github.com/hivecommons/hive/issues/18866)): the gate exists to get a reproducible build out of an outside reporter, so the sweep never applies it to +- an issue authored by the hive's own accounts (`project.ai_author`, `[bot]` logins, the App); +- an issue authored by an owner or maintainer: GitHub author association in `project.issue_filter.reporter_trust.trusted_associations` (default OWNER, MEMBER, COLLABORATOR); +- an issue whose **body** names a concrete repository file path: a repo-relative path under a known top-level directory (`src/`, `pkg/`, `cmd/`, `internal/`, `docs/`, `bin/`, `config/`, `dashboard/`, `examples/`, `systemd/`, `launchd/`, `githooks/`, `.github/`) ending in a known source or config extension (`.go`, `.js`, `.ts`, `.py`, `.sh`, `.yaml`, `.json`, `.md`, ...), such as `src/pkg/github/client.go`. Absolute paths, URLs and bare file names do not count; comments are not scanned. **This signal is self-attested:** the hive only pattern-matches the text and never checks that the path exists, so any outside reporter can skip the SHA gate by writing a path such as `src/pkg/x.go` in the issue body. That is accepted by design in #18866 (a reporter who cites the code is treated as informed), not a hardened check; +- an issue carrying `sha-waived` (below). + +An exemption is evaluated on every sweep, so a `needs-sha` that was applied before the issue qualified is removed by the next sweep. Outside reporters whose body has neither a SHA nor such a path are still held. **Who applies it:** Hive. **Checked by:** SHA-hold sweep. **When:** Eval tick SHA sweep. -**Release or override.** Add SHA evidence, or remove the label +**Release or override.** Post a commit SHA in a comment; or a maintainer waives the requirement (`sha-waived`, next entry); or remove the label by hand (the sweep re-adds it on the next tick unless the issue is waived or exempt). + +**Dashboard.** An issue held by `needs-sha` shows the pill *Held: needs commit SHA* on its Activity Monitor row (hover: "Post a commit SHA in the issue, or waive this requirement.") and a *held: post a commit SHA* note on the Open chevron, from the `sha_hold` field of `GET /api/stage-tracker`. A `hold` already shows its own pill. + +**Configuration and implementation.** `issues.sha_hold_trusted_label` (default `needs-sha`; `hold` is treated as unset, since the sweep never applies `hold`); `project.issue_filter.reporter_trust.trusted_associations` for the maintainer exemption (`src/pkg/github/client.go` `EnforceSHAHold`, `src/pkg/github/sha_hold_exempt.go`, `src/pkg/dashboard/stage_tracker_sha_hold.go`) + +#### `sha-waived` from the SHA-hold override + +**Applies to:** Issues. **Kind:** Override (persistent marker). + +A maintainer's waiver of the SHA requirement for one issue ([#18866](https://github.com/hivecommons/hive/issues/18866)). While `sha-waived` is on the issue the SHA sweep neither applies nor keeps `needs-sha` (a lingering one is removed on the next sweep), and the issue is eligible for the stage-label pass and agent work like any other. Description: "A maintainer waived the commit-SHA requirement; hive will not hold this issue for a SHA." + +**Who applies it:** A person: the Activity Monitor row menu's *Waive SHA requirement* (`POST /api/repos/{owner}/{repo}/items/{number}/sha-waiver`, `{"waived": true}`), or by hand. The dashboard action is gated like releasing a `hold` (the verified owner role, or write/maintain/admin on the repo), removes `needs-sha` at once, and posts one App-authored comment carrying ``, from which the pill reads *SHA waived by *. + +**Checked by:** SHA-hold sweep, enumeration. **When:** Eval tick SHA sweep; enumeration. + +**Release or override.** *Restore SHA requirement* in the row menu (or removing the label) re-arms the gate: the next sweep holds the issue again if it still has no SHA and no exemption. The hive never adds or removes `sha-waived` itself. -**Configuration and implementation.** `issues.sha_hold_trusted_label` (default `needs-sha`; `hold` is treated as unset, since the sweep never applies `hold`) +**Configuration and implementation.** None; the label name is fixed (`src/pkg/github/sha_hold_exempt.go` `SHAWaivedLabel`, `src/pkg/dashboard/api_repo_item_sha_waiver.go`) ### Issue admission and triage diff --git a/src/docs/notifications.md b/src/docs/notifications.md index 3ec7164edb..7bd6bfa88e 100644 --- a/src/docs/notifications.md +++ b/src/docs/notifications.md @@ -473,6 +473,7 @@ without a class. Review submissions and review requests are always counted as | `dashboard.(*Server).handleRepoItemBlockerClosePartial` | `status` | | | `dashboard.(*Server).handleRepoItemDecision` | `status` | | | `dashboard.(*Server).handleRepoItemSentinelConfirm` | `status` | | +| `dashboard.(*Server).handleRepoItemSHAWaiver` | `status` | | | `dashboard.(*Server).handleReviewQueueSupersededClose` | `status` | | | `dashboard.(*Server).mirrorPlanWith` | `status` | | | `github.(*Client).CloseIssueForConfiguredLinePR` | `status` | | diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index 8e6d171b0c..eae1868a6b 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -207,7 +207,7 @@ Top-level YAML keys accepted by `config.Config`: | `dedupe.advisory_autoclose` | `true`. | The close-on-merge backfill works the dedupe agent's advisory checklists itself ([#15754](https://github.com/hivecommons/hive/issues/15754)): for every open hive-authored issue whose body opens with `` it ticks each `- [ ] #N …` task line whose #N is closed or merged (one body edit per sweep, idempotent) and, once every line is ticked, comments `All N items resolved (#a closed, #b merged …) — closing this advisory.` and closes the issue as `completed`. A checklist with open items expires after seven days. The Activity Monitor never parks an advisory at 045 regardless. `false` leaves checklists untouched (they still expire). Env/dashboard: yaml-only. | | `issues.close_on_merge_recheck` | `24h`. | How long a merged-PR claim keeps its settled close-on-merge verdict before the ledger sweep re-verifies it against the API. Once a sweep reaches a final verdict for a claim — issue closed, already closed, Hive marker present, awaiting confirmation, untrusted author, reopened by a person, or PR not merged — it stamps `close_on_merge_settled_at` on the claim and later sweeps skip the claim with no API call until this window elapses. Transient failures (issue, timeline or comment reads/writes that errored) never settle and retry on the next sweep as before. The marker follows the claim while the same PR claims the issue and resets when a different PR takes it over. Env override: `HIVE_CLOSE_ON_MERGE_RECHECK` (Go duration). | | `issues.reporter_confirmation` | `false`. | Legacy opt-in switch for hives that want every human-filed bug-family issue to wait for reporter verification before close. Leave false for the default close-on-merge policy; add `hive: needs-confirmation` to an individual issue when only that issue needs the gate. `hive: reporter-confirmed` and `hive: close-on-merge` remain accepted legacy bypasses. | -| `issues.sha_hold_trusted_label` | `needs-sha`. | Soft label the SHA-hold sweep applies to a `kind/bug` without a commit SHA when the reporter's author association is in `project.issue_filter.reporter_trust.trusted_associations` (default OWNER/MEMBER/COLLABORATOR), instead of the hard `hold` (#12002). The label keeps the issue out of agent work until it is removed. A SHA-hold `hold` already on such an issue is swapped for this label. Set to `hold` to restore the hard hold for every reporter. | +| `issues.sha_hold_trusted_label` | `needs-sha`. | Label the SHA-hold sweep applies to an outside reporter's `kind/bug` without a commit SHA. The label keeps the issue out of agent work until it is removed. Owners and maintainers (author association in `project.issue_filter.reporter_trust.trusted_associations`, default OWNER/MEMBER/COLLABORATOR), the hive's own accounts, issues whose body names concrete repo file paths (self-attested, never checked to exist: a reporter can write one to skip the gate), and issues carrying `sha-waived` are exempt and never get it (#18866). Set to `hold` to restore the hard hold for every reporter. | | `issues.lift_hive_hard_suppress` | `true`. | Runs the hard-suppress reconcile (#12002): a `hold` or `blocked` label on an open issue is lifted when Hive provably applied it (newest label event is a `labeled` by the App bot; for `hold`, paired with the `` notice) and a PR cross-referencing the issue merged after it. Hive posts one note carrying ``. Human-applied labels are never lifted. Skipped with the other unstick steps when the API budget is critical. | | `issues.hard_suppress_reconcile_interval` | `30m`. | Minimum time between hard-suppress reconcile passes. | | `issues.rfc_existing_check.enabled` | `false`. | Triage existing-coverage check (#13575): new open issues labelled `rfc`, `enhancement` or `kind/feature` get one comment that lists the existing settings that may already cover the request. Each setting links to Settings with the search set to its key. The comment carries `` and is never posted twice. The check never labels or closes issues. Tuning keys are `post_when_nothing_found`, `labels`, `max_matches` and `max_age`; see [Triage: does this RFC already exist?](../settings.md#triage-does-this-rfc-already-exist). | diff --git a/src/hive.yaml.example b/src/hive.yaml.example index c89075cb6c..988fb198fa 100644 --- a/src/hive.yaml.example +++ b/src/hive.yaml.example @@ -174,7 +174,8 @@ project: # close_on_merge: true # close_on_merge_backfill_interval: 1h # reporter_confirmation: false -# # Trusted reporters' SHA-less bugs get this soft label, not `hold` (#12002). +# # Non-exempt reporters' SHA-less bugs get this soft label, not `hold` (#12002). +# # Owners/maintainers, hive accounts, issues naming repo paths and waived issues are exempt (#18866). # sha_hold_trusted_label: needs-sha # # Lift hive-applied hold/blocked once a referencing PR merges (#12002). # lift_hive_hard_suppress: true diff --git a/src/pkg/config/issues.go b/src/pkg/config/issues.go index 486301f7f3..4c6601d975 100644 --- a/src/pkg/config/issues.go +++ b/src/pkg/config/issues.go @@ -45,11 +45,12 @@ type IssuesConfig struct { // needs reporter verification. ReporterConfirmation *bool `yaml:"reporter_confirmation,omitempty" json:"reporter_confirmation,omitempty"` // SHAHoldTrustedLabel is the soft label the SHA-hold sweep applies to a - // bug filed by a reporter in issue_filter.reporter_trust's trusted - // associations (OWNER/MEMBER/COLLABORATOR by default) when no commit SHA - // is present. Unset uses DefaultSHAHoldTrustedLabel. Since - // hivecommons/hive#18468 the sweep applies this label to every reporter - // and never applies `hold`; "hold" is treated as unset. + // bug without a commit SHA. Unset uses DefaultSHAHoldTrustedLabel. Since + // hivecommons/hive#18468 the sweep never applies `hold` ("hold" is + // treated as unset); since #18866 it exempts the hive's own accounts, + // reporters in issue_filter.reporter_trust's trusted associations + // (OWNER/MEMBER/COLLABORATOR by default), issues whose body names a repo + // file path, and issues carrying sha-waived. SHAHoldTrustedLabel *string `yaml:"sha_hold_trusted_label,omitempty" json:"sha_hold_trusted_label,omitempty"` // LiftHiveHardSuppress enables the reconcile that lifts a `hold`/`blocked` // label hive itself applied once a PR referencing the issue has merged diff --git a/src/pkg/dashboard/api.go b/src/pkg/dashboard/api.go index 73811c04cf..683adbf33e 100644 --- a/src/pkg/dashboard/api.go +++ b/src/pkg/dashboard/api.go @@ -329,6 +329,7 @@ func (s *Server) RegisterAPI(deps *Dependencies) { // monitor's ✓ badge remembers them (operator_actions.go). s.mux.HandleFunc("GET /api/repos/{owner}/{repo}/items/{number}", s.handleRepoItemDetail) s.mux.HandleFunc("POST /api/repos/{owner}/{repo}/items/{number}/hold", s.recordOperatorAction(s.handleRepoItemHold)) + s.mux.HandleFunc("POST /api/repos/{owner}/{repo}/items/{number}/sha-waiver", s.handleRepoItemSHAWaiver) s.mux.HandleFunc("POST /api/repos/{owner}/{repo}/items/{number}/decision", s.recordOperatorAction(s.handleRepoItemDecision)) s.mux.HandleFunc("POST /api/repos/{owner}/{repo}/items/{number}/sentinel-confirm", s.recordOperatorAction(s.handleRepoItemSentinelConfirm)) // Per-item maintainer notes shared across the hive's maintainers diff --git a/src/pkg/dashboard/api_repo_item_sha_waiver.go b/src/pkg/dashboard/api_repo_item_sha_waiver.go new file mode 100644 index 0000000000..f1c5b0be9a --- /dev/null +++ b/src/pkg/dashboard/api_repo_item_sha_waiver.go @@ -0,0 +1,203 @@ +package dashboard + +import ( + "context" + "encoding/json" + "net/http" + "strconv" + "strings" + "time" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/github" +) + +// "Waive SHA requirement" / "Restore SHA requirement" from the activity +// monitor's row menu (hivecommons/hive#18866): the override for the SHA-hold +// gate. Waiving adds the persistent `sha-waived` label (the SHA sweep never +// re-adds `needs-sha` while it is on), removes `needs-sha` so the issue is +// released at once, and posts one App-authored comment carrying a hidden +// marker that names who waived it, which is how the pill reads "SHA waived by +// " after a restart. Restoring removes `sha-waived`; the next sweep +// holds the issue again if it still has no SHA and no exemption. Authorised +// exactly like the hold toggle (verified owner role, or write permission on +// the repo); audited under the dashboard user. Issues only. + +const ( + shaWaiverAuditAction = "repo_item_sha_waiver" + shaWaiverLabelColor = "0e8a16" + + rowActionSHAWaived = "sha-waived" + rowActionSHARestored = "sha-restored" +) + +type repoSHAWaiverRequest struct { + Waived bool `json:"waived"` +} + +type repoSHAWaiverResponse struct { + OK bool `json:"ok"` + Repo string `json:"repo"` + Number int `json:"number"` + Waived bool `json:"waived"` + Added []string `json:"added"` + Removed []string `json:"removed"` + MinStatusSeq uint64 `json:"minStatusSeq"` + // Result is the shared row-action outcome for the dashboard's toast. + Result *RowActionResult `json:"result,omitempty"` +} + +func (s *Server) handleRepoItemSHAWaiver(w http.ResponseWriter, r *http.Request) { + owner, repoName, number, ok := s.parseRepoItemPath(w, r) + if !ok { + return + } + allowed, status, msg := s.canToggleRepoHold(r, owner, repoName) + if !allowed { + jsonError(w, msg, status) + return + } + if s.deps == nil || s.deps.GHClient == nil || s.deps.GHClient.GoGitHub() == nil { + jsonError(w, "GitHub client not configured", http.StatusServiceUnavailable) + return + } + var body repoSHAWaiverRequest + if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 8<<10)).Decode(&body); err != nil { + jsonError(w, "invalid request body: "+err.Error(), http.StatusBadRequest) + return + } + ctx := context.Background() + if s.deps.Ctx != nil { + ctx = s.deps.Ctx + } + repoFull := owner + "/" + repoName + if !s.watchesRepo(repoFull) { + jsonError(w, "repository is not configured for this hive", http.StatusForbidden) + return + } + issue, resp, err := s.deps.GHClient.GoGitHub().Issues.Get(ctx, owner, repoName, number) + if err != nil { + if resp != nil && resp.StatusCode == http.StatusNotFound { + jsonError(w, "issue not found", http.StatusNotFound) + return + } + jsonError(w, err.Error(), http.StatusBadGateway) + return + } + if issue.IsPullRequest() { + jsonError(w, "only issues carry the SHA requirement", http.StatusNotFound) + return + } + labels := make([]string, 0, len(issue.Labels)) + for _, label := range issue.Labels { + labels = append(labels, label.GetName()) + } + user := strings.TrimSpace(r.Header.Get("X-Hive-User")) + target := rowActionTarget(repoFull, rowActionTargetIssue, number) + out := repoSHAWaiverResponse{OK: true, Repo: repoFull, Number: number, Waived: body.Waived, Added: []string{}, Removed: []string{}} + + if body.Waived { + if shaLabelOn(labels, github.SHAWaivedLabel) { + res := rowActionNoopResult(target, "the SHA requirement was already waived", time.Time{}, "") + out.Result = &res + jsonResponse(w, out) + return + } + if err := s.deps.GHClient.EnsureIssueLabel(ctx, repoFull, github.SHAWaivedLabel, shaWaiverLabelColor, github.SHAWaivedLabelDescription); err != nil { + jsonError(w, err.Error(), http.StatusBadGateway) + return + } + if err := s.deps.GHClient.AddLabels(ctx, repoFull, number, []string{github.SHAWaivedLabel}); err != nil { // writeback:solicited a maintainer waived or restored the SHA requirement from the row menu + jsonError(w, err.Error(), http.StatusBadGateway) + return + } + out.Added = []string{github.SHAWaivedLabel} + // Release the hold now rather than at the next sweep. + for _, name := range []string{s.shaHoldLabelName(), config.DefaultSHAHoldTrustedLabel} { + if shaLabelOn(labels, name) && !shaLabelOn(out.Removed, name) { + if err := s.deps.GHClient.RemoveLabel(ctx, repoFull, number, name); err != nil { // writeback:solicited a maintainer waived or restored the SHA requirement from the row menu + jsonError(w, err.Error(), http.StatusBadGateway) + return + } + out.Removed = append(out.Removed, name) + } + } + by := user + if by == "" { + by = "owner" + } + s.deps.GHClient.RecordSHAWaiver(repoFull, number, by) + note := github.SHAWaivedMarker(by) + "\nThe commit-SHA requirement for this issue was waived by `" + by + "`. " + + "The hive will work it without a SHA. A maintainer can restore the requirement from the dashboard." + if err := s.deps.GHClient.CreateIssueComment(ctx, repoFull, number, note); err != nil && s.logger != nil { // writeback:solicited a maintainer waived or restored the SHA requirement from the row menu + s.logger.Warn("SHA waiver: could not post the waiver note", "repo", repoFull, "issue", number, "error", err) + } + out.Result = &RowActionResult{Action: rowActionSHAWaived, Target: target, + Outcome: "SHA requirement waived: `" + github.SHAWaivedLabel + "` added" + removedClause(out.Removed) + ".", + Next: "The hive may work this issue on its next pass; the SHA sweep will not hold it again until the requirement is restored."} + } else { + if !shaLabelOn(labels, github.SHAWaivedLabel) { + res := rowActionNoopResult(target, "the SHA requirement was not waived", time.Time{}, "") + out.Result = &res + jsonResponse(w, out) + return + } + if err := s.deps.GHClient.RemoveLabel(ctx, repoFull, number, github.SHAWaivedLabel); err != nil { // writeback:solicited a maintainer waived or restored the SHA requirement from the row menu + jsonError(w, err.Error(), http.StatusBadGateway) + return + } + out.Removed = []string{github.SHAWaivedLabel} + s.deps.GHClient.RecordSHAWaiver(repoFull, number, "") + out.Result = &RowActionResult{Action: rowActionSHARestored, Target: target, + Outcome: "SHA requirement restored: `" + github.SHAWaivedLabel + "` removed.", + Next: "The next SHA sweep holds the issue again if it still has no commit SHA and no exemption."} + } + s.auditFromRequest(r, shaWaiverAuditAction, auditDetail("repo", repoFull, "number", strconv.Itoa(number), "waived", strconv.FormatBool(body.Waived), "added", strings.Join(out.Added, ","), "removed", strings.Join(out.Removed, ",")), "") + out.MinStatusSeq = s.refreshItemSnapshotNow(ctx, repoFull, number) + jsonResponse(w, out) +} + +func removedClause(removed []string) string { + if len(removed) == 0 { + return "" + } + return ", `" + strings.Join(removed, "`, `") + "` removed" +} + +// refreshItemSnapshotNow re-reads one item and patches the status snapshot so the +// row reads its new labels at once. It is not specific to the SHA waiver: a +// row action that only changes labels can use it instead of copying the +// status-sequence bump (api_repo_hold.go applyRepoHoldToStatus moves hold +// items between lists and does something different). Best effort: the labels are already +// saved on GitHub, so a failed read only means the next poll shows them. +func (s *Server) refreshItemSnapshotNow(ctx context.Context, repo string, number int) uint64 { + watched := repo + if cfg := s.deps.Config; cfg != nil { + for _, w := range cfg.Project.Repos { + if strings.EqualFold(config.QualifyRepo(cfg.Project.Org, w), repo) { + watched = w + break + } + } + } + snap, err := s.deps.GHClient.FetchWebhookItemSnapshot(ctx, watched, number, false) + if err != nil { + if s.logger != nil { + s.logger.Warn("SHA waiver: could not refresh the row", "repo", repo, "issue", number, "error", err) + } + return 0 + } + s.applyWebhookItemSnapshots([]github.WebhookItemSnapshot{snap}) + s.statusMu.Lock() + s.statusMutationEpoch++ + s.statusSeq++ + seq := s.statusSeq + if s.status != nil { + next := *s.status + next.StatusSeq = seq + s.status = &next + } + s.statusMu.Unlock() + s.invalidateStageTrackerForWebhook() + return seq +} diff --git a/src/pkg/dashboard/stage_tracker.go b/src/pkg/dashboard/stage_tracker.go index 6940323f6a..9909f98a93 100644 --- a/src/pkg/dashboard/stage_tracker.go +++ b/src/pkg/dashboard/stage_tracker.go @@ -459,6 +459,10 @@ type StageTrackerItem struct { // "Held by hive · reporter trust (issue #N by @X, contributor)" or // "Held by @login" instead of a bare "hold". Hold *StageTrackerHold `json:"hold,omitempty"` + // SHAHold says an issue is held by the SHA-hold gate (`needs-sha`) or + // that a maintainer waived it (`sha-waived`), with the ready-made pill, + // hover text and chevron note (hivecommons/hive#18866). Absent otherwise. + SHAHold *StageTrackerSHAHold `json:"sha_hold,omitempty"` // RegressedFrom / RegressedTo / RegressedAt / RegressedReason narrate // the unresolved regression behind the `regressed` modifier: the // high-water stage the item fell from, the stage that fall landed on diff --git a/src/pkg/dashboard/stage_tracker_build.go b/src/pkg/dashboard/stage_tracker_build.go index ec02f7b665..57966075d6 100644 --- a/src/pkg/dashboard/stage_tracker_build.go +++ b/src/pkg/dashboard/stage_tracker_build.go @@ -298,6 +298,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto Labels: append([]string(nil), issue.Labels...), CreatedAt: timePtr(issue.CreatedAt), UpdatedAt: timePtr(issue.UpdatedAt), Bucket: bucket, BucketReason: bucketReason, URL: overviewItemURL(issue.URL, issue.Repo, issue.Number, "issue", status.GitHubBaseURL)} + it.SHAHold = s.stageTrackerSHAHold(repoName, issue.Number, issue.Labels) it.Children = issue.Children if it.Children == nil { it.Children = progress diff --git a/src/pkg/dashboard/stage_tracker_sha_hold.go b/src/pkg/dashboard/stage_tracker_sha_hold.go new file mode 100644 index 0000000000..b41b671712 --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_sha_hold.go @@ -0,0 +1,76 @@ +package dashboard + +import ( + "strings" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/github" +) + +// The SHA-hold gate keeps the hive off a primary-repo bug until a commit SHA +// is posted (labels-and-control-signals reference: `needs-sha`). Before +// hivecommons/hive#18866 the row said only "Open · since 11h" with every later +// stage empty; this is the pill, hover and chevron note that say why, and how +// to lift it, plus the waived state a maintainer's override leaves behind. + +const ( + // SHA hold states on StageTrackerSHAHold.State. + stageTrackerSHAHeld = "held" + stageTrackerSHAWaived = "waived" + + stageTrackerSHAHeldPill = "Held: needs commit SHA" + stageTrackerSHAHeldTip = "Post a commit SHA in the issue, or waive this requirement." + stageTrackerSHAHeldNote = "held: post a commit SHA" + stageTrackerSHAWaivedTip = "A maintainer waived the commit-SHA requirement; the hive no longer holds this issue for a SHA. Restore the requirement from the row's menu." + stageTrackerSHAWaivedNote = "SHA waived" +) + +// StageTrackerSHAHold is the row's SHA-hold state in payload shape. State is +// "held" (needs-sha is on and nobody waived it) or "waived" (sha-waived is on; +// By names the maintainer when known). The strings are ready to draw. +type StageTrackerSHAHold struct { + State string `json:"state"` + // Label is the label the state stands for (needs-sha or sha-waived). + Label string `json:"label"` + By string `json:"by,omitempty"` + Pill string `json:"pill"` + Tip string `json:"tip"` + Note string `json:"note"` +} + +func (s *Server) shaHoldLabelName() string { + if s != nil && s.deps != nil && s.deps.Config != nil { + return s.deps.Config.Issues.EffectiveSHAHoldTrustedLabel() + } + return config.DefaultSHAHoldTrustedLabel +} + +func shaLabelOn(labels []string, want string) bool { + for _, l := range labels { + if strings.EqualFold(strings.TrimSpace(l), want) { + return true + } + } + return false +} + +// stageTrackerSHAHold derives the row's SHA-hold state from its labels; nil +// when the issue is neither held by the gate nor waived. +func (s *Server) stageTrackerSHAHold(repo string, number int, labels []string) *StageTrackerSHAHold { + if shaLabelOn(labels, github.SHAWaivedLabel) { + by := "" + if s != nil && s.deps != nil { + by = s.deps.GHClient.SHAWaivedBy(repo, number) + } + pill := "SHA waived" + if by != "" { + pill += " by " + by + } + return &StageTrackerSHAHold{State: stageTrackerSHAWaived, Label: github.SHAWaivedLabel, By: by, Pill: pill, Tip: stageTrackerSHAWaivedTip, Note: stageTrackerSHAWaivedNote} + } + name := s.shaHoldLabelName() + if shaLabelOn(labels, name) || shaLabelOn(labels, config.DefaultSHAHoldTrustedLabel) { + return &StageTrackerSHAHold{State: stageTrackerSHAHeld, Label: name, Pill: stageTrackerSHAHeldPill, Tip: stageTrackerSHAHeldTip, Note: stageTrackerSHAHeldNote} + } + return nil +} diff --git a/src/pkg/dashboard/stage_tracker_sha_hold_test.go b/src/pkg/dashboard/stage_tracker_sha_hold_test.go new file mode 100644 index 0000000000..af744e2940 --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_sha_hold_test.go @@ -0,0 +1,186 @@ +package dashboard + +import ( + "encoding/json" + "log/slog" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/github" +) + +// hivecommons/hive#18866: an issue held by the SHA-hold gate shows why on its +// row (pill, hover, chevron note) and a maintainer can waive the requirement +// from the row menu; the waiver is gated like releasing a `hold`. + +func TestStageTrackerSHAHoldPayload(t *testing.T) { + srv := newFullServer(t) + if got := srv.stageTrackerSHAHold("o/r", 1, []string{"kind/bug"}); got != nil { + t.Fatalf("plain issue: sha_hold = %+v, want nil", got) + } + held := srv.stageTrackerSHAHold("o/r", 1, []string{"kind/bug", "needs-sha"}) + if held == nil || held.State != "held" || held.Pill != "Held: needs commit SHA" || + held.Tip != "Post a commit SHA in the issue, or waive this requirement." || held.Note == "" { + t.Fatalf("held: %+v", held) + } + waived := srv.stageTrackerSHAHold("o/r", 1, []string{"kind/bug", "needs-sha", "sha-waived"}) + if waived == nil || waived.State != "waived" || waived.Pill != "SHA waived" { + t.Fatalf("waived with nobody known: %+v", waived) + } + srv.deps.GHClient = github.NewClient("t", "o", []string{"r"}, slog.Default(), "") + srv.deps.GHClient.RecordSHAWaiver("o/r", 1, "alice") + waived = srv.stageTrackerSHAHold("o/r", 1, []string{"sha-waived"}) + if waived == nil || waived.Pill != "SHA waived by alice" || waived.By != "alice" { + t.Fatalf("waived by alice: %+v", waived) + } +} + +func postSHAWaiver(t *testing.T, srv *Server, user string, owner, waived bool) *httptest.ResponseRecorder { + t.Helper() + body := `{"waived":false}` + if waived { + body = `{"waived":true}` + } + req := httptest.NewRequest(http.MethodPost, "/api/repos/testorg/testrepo/items/7/sha-waiver", strings.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + if user != "" { + req.Header.Set("X-Hive-User", user) + } + if owner { + markOwnerRequest(req) + } + w := httptest.NewRecorder() + srv.mux.ServeHTTP(w, req) + return w +} + +func TestRepoItemSHAWaiverAuthorizationAndLabels(t *testing.T) { + mock := &acceptTriageMock{permission: "write", issueLabels: []string{"kind/bug", "needs-sha"}} + srv := newAcceptTriageServer(t, mock) + + // Not privileged: a reader and an anonymous caller cannot override. + if w := postSHAWaiver(t, srv, "reader", false, true); w.Code != http.StatusForbidden { + t.Fatalf("reader: code=%d want 403 body=%s", w.Code, w.Body.String()) + } + if w := postSHAWaiver(t, srv, "", false, true); w.Code != http.StatusUnauthorized { + t.Fatalf("anonymous: code=%d want 401 body=%s", w.Code, w.Body.String()) + } + if len(mock.added)+len(mock.removed) != 0 { + t.Fatalf("refused requests wrote labels: added=%v removed=%v", mock.added, mock.removed) + } + + w := postSHAWaiver(t, srv, "writer", false, true) + if w.Code != http.StatusOK { + t.Fatalf("writer: code=%d body=%s", w.Code, w.Body.String()) + } + var resp repoSHAWaiverResponse + if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil { + t.Fatal(err) + } + if !resp.OK || !resp.Waived || resp.Result == nil || resp.Result.Action != rowActionSHAWaived { + t.Fatalf("response = %+v", resp) + } + if got := strings.Join(mock.added, ","); got != "sha-waived" { + t.Fatalf("added = %q, want sha-waived", got) + } + if got := strings.Join(mock.removed, ","); got != "needs-sha" { + t.Fatalf("removed = %q, want needs-sha released at once", got) + } + if got := srv.deps.GHClient.SHAWaivedBy("testorg/testrepo", 7); got != "writer" { + t.Fatalf("waived by = %q, want writer", got) + } + var audited bool + for _, entry := range srv.GetAudit().Recent(10) { + if entry.Action == shaWaiverAuditAction && entry.User == "writer" { + audited = true + } + } + if !audited { + t.Fatal("no audit entry for the waiver") + } + + // Waiving again is a no-op. + mock.added, mock.removed = nil, nil + if w := postSHAWaiver(t, srv, "writer", false, true); w.Code != http.StatusOK || len(mock.added)+len(mock.removed) != 0 { + t.Fatalf("repeat waive: code=%d added=%v removed=%v", w.Code, mock.added, mock.removed) + } + + // Restore removes only sha-waived; the sweep re-holds it later. + w = postSHAWaiver(t, srv, "writer", false, false) + if w.Code != http.StatusOK || strings.Join(mock.removed, ",") != "sha-waived" { + t.Fatalf("restore: code=%d removed=%v body=%s", w.Code, mock.removed, w.Body.String()) + } + if got := srv.deps.GHClient.SHAWaivedBy("testorg/testrepo", 7); got != "" { + t.Fatalf("waived by after restore = %q, want empty", got) + } + + // The verified owner role passes without a permission lookup. + mock.added, mock.removed = nil, nil + mock.issueLabels = []string{"kind/bug", "needs-sha"} + if w := postSHAWaiver(t, srv, "", true, true); w.Code != http.StatusOK || strings.Join(mock.added, ",") != "sha-waived" { + t.Fatalf("owner: code=%d added=%v", w.Code, mock.added) + } +} + +func TestRepoItemSHAWaiverRefusesPullRequests(t *testing.T) { + mock := &acceptTriageMock{permission: "write", isPullRequest: true, issueLabels: []string{"needs-sha"}} + srv := newAcceptTriageServer(t, mock) + if w := postSHAWaiver(t, srv, "writer", false, true); w.Code != http.StatusNotFound || len(mock.added) != 0 { + t.Fatalf("PR: code=%d added=%v, want 404 and no write", w.Code, mock.added) + } +} + +func TestStageTrackerSHAHoldPillAndMenu(t *testing.T) { + html := indexHTML(t) + for _, want := range []string{"${shaHoldNote}", "stageTrackerSHAHoldChipHtml(item)", "/sha-waiver"} { + if !strings.Contains(html, want) { + t.Errorf("index.html lacks %q", want) + } + } + runStageTrackerRowActionsScript(t, stageTrackerRowActionsPreamble(t, html)+"\n"+ + jsFunc(t, html, "stageTrackerSHAHoldOf")+"\n"+ + jsFunc(t, html, "stageTrackerSHAHoldChipHtml")+"\n"+ + jsFunc(t, html, "stageTrackerSHAHoldNoteHtml")+` +const ids = as => as.map(a => a.id); +const heldHold = { state: 'held', label: 'needs-sha', pill: 'Held: needs commit SHA', tip: 'Post a commit SHA in the issue, or waive this requirement.', note: 'held: post a commit SHA' }; +const item = { repo: 'o/r', kind: 'issue', number: 18740, url: 'u', stage: 0, modifiers: [], sha_hold: heldHold }; + +// The pill names the reason and carries how to lift it. +const chip = stageTrackerSHAHoldChipHtml(item); +assert.ok(chip.includes('Held: needs commit SHA'), chip); +assert.ok(chip.includes('title="Post a commit SHA in the issue, or waive this requirement."'), chip); +assert.ok(chip.includes('ham-sha-held'), chip); +// The note rides the Open chevron. +assert.ok(stageTrackerSHAHoldNoteHtml(item).includes('held: post a commit SHA')); +// Nothing for an ordinary issue, a PR, or an unknown state. +assert.strictEqual(stageTrackerSHAHoldChipHtml({ kind: 'issue', number: 1 }), ''); +assert.strictEqual(stageTrackerSHAHoldChipHtml({ kind: 'pr', sha_hold: heldHold }), ''); +assert.strictEqual(stageTrackerSHAHoldNoteHtml({ kind: 'issue', sha_hold: { state: 'x', pill: 'p' } }), ''); + +// Held: the menu offers Waive; it is gated like Hold (canHold). +let as = stageTrackerRowActions(item, { user: true, canHold: true, canHuman: true }); +assert.ok(ids(as).includes('sha-waive') && !ids(as).includes('sha-restore'), ids(as).join()); +assert.strictEqual(as.find(a => a.id === 'sha-waive').label, 'Waive SHA requirement'); +assert.strictEqual(as.find(a => a.id === 'sha-waive').enabled, true); +as = stageTrackerRowActions(item, { user: true, canHold: false, canHuman: true }); +const waive = as.find(a => a.id === 'sha-waive'); +assert.strictEqual(waive.enabled, false, 'a non-privileged viewer sees it disabled'); +assert.ok(waive.why, 'with the reason'); + +// Waived: the pill reads who, the item flips to Restore. +const waived = { ...item, sha_hold: { state: 'waived', label: 'sha-waived', by: 'alice', pill: 'SHA waived by alice', tip: 't', note: 'SHA waived' } }; +assert.ok(stageTrackerSHAHoldChipHtml(waived).includes('SHA waived by alice')); +as = stageTrackerRowActions(waived, { user: true, canHold: true, canHuman: true }); +assert.ok(ids(as).includes('sha-restore') && !ids(as).includes('sha-waive')); +assert.strictEqual(as.find(a => a.id === 'sha-restore').label, 'Restore SHA requirement'); + +// No SHA state: no entry. +assert.ok(!ids(stageTrackerRowActions({ ...item, sha_hold: null }, { user: true, canHold: true })).some(i => i.indexOf('sha-') === 0)); + +// The request goes to the waiver endpoint. +assert.deepStrictEqual(stageTrackerActionRequest(item, 'sha-waive'), { url: '/api/repos/o/r/items/18740/sha-waiver', body: { waived: true } }); +assert.deepStrictEqual(stageTrackerActionRequest(waived, 'sha-restore'), { url: '/api/repos/o/r/items/18740/sha-waiver', body: { waived: false } }); +`) +} diff --git a/src/pkg/dashboard/static-src/css/tracker.css b/src/pkg/dashboard/static-src/css/tracker.css index a28c0f6674..c4925f1714 100644 --- a/src/pkg/dashboard/static-src/css/tracker.css +++ b/src/pkg/dashboard/static-src/css/tracker.css @@ -345,6 +345,8 @@ rides last; past dashboard.stage_tracker.waiting_push_stale_h it takes the muted warning tone. "@zoe pushed abc1234 · 2m" links to the commit. */ .ham-push-stale { color: color-mix(in srgb, var(--status-warn) 70%, var(--text-faint)); } + .ham-badge-sha-hold { color: var(--status-warn); border-color: color-mix(in srgb, var(--status-warn) 55%, transparent); } + .ham-badge-sha-hold.ham-sha-waived { color: var(--text-muted); border-color: color-mix(in srgb, var(--text-muted) 45%, transparent); } .ham-badge-push { text-decoration: none; } .ham-badge-push:hover { color: var(--text-muted); } /* Presence indicator on a waiting-on pill (hive PR 15051): who the row diff --git a/src/pkg/dashboard/static-src/js/tracker-actions.js b/src/pkg/dashboard/static-src/js/tracker-actions.js index d826c009b3..9263e0233e 100644 --- a/src/pkg/dashboard/static-src/js/tracker-actions.js +++ b/src/pkg/dashboard/static-src/js/tracker-actions.js @@ -57,7 +57,7 @@ // is not generic: a row offers it either from the nudge (`adoption`) // or as a server decision option (a contributor PR's DCO / fixer // exhaustion, where it replaced "re-author"), never both. - const STAGE_TRACKER_GENERIC_ACTIONS = ['hold', 'release', 'retry', 'needs-human', 'accept-triage', 'open', 'copy', 'decide:delegate', 'decide:delegate-all', 'decide:close-issue']; + const STAGE_TRACKER_GENERIC_ACTIONS = ['hold', 'release', 'sha-waive', 'sha-restore', 'retry', 'needs-human', 'accept-triage', 'open', 'copy', 'decide:delegate', 'decide:delegate-all', 'decide:close-issue']; const _stageTrackerCloseIssueBusy = new Set(); // Accept triage shows on an issue the chevron calls "Triage needed": // stage 015, or the needs-triage pill on a pre-claim stage (010 / 017 / @@ -505,6 +505,13 @@ out.push(has('hold') ? { id: 'release', label: 'Release hold', enabled: write, why: write ? '' : STAGE_TRACKER_WHY_WRITE, sep: triage && !target } : { id: 'hold', label: 'Hold', enabled: write, why: write ? '' : STAGE_TRACKER_WHY_WRITE, sep: triage && !target }); + // A SHA-held issue (needs-sha) offers the override next to the hold + // actions: Waive SHA requirement, then Restore once it is waived + // (hivecommons/hive#18866). Same roles as releasing a hold. + const shaHold = typeof stageTrackerSHAHoldOf === 'function' ? stageTrackerSHAHoldOf(item) : null; + if (shaHold) out.push(shaHold.state === 'waived' + ? { id: 'sha-restore', label: 'Restore SHA requirement', enabled: write, why: write ? '' : STAGE_TRACKER_WHY_WRITE } + : { id: 'sha-waive', label: 'Waive SHA requirement', hint: 'hive works it without a SHA', enabled: write, why: write ? '' : STAGE_TRACKER_WHY_WRITE }); out.push({ id: 'retry', label: 'Re-evaluate now', hint: 'rescan', enabled: true, why: '' }); // A model-bound row whose state the model hands to an agent profile // (cncf/techdocs#395): the owner can send it now. @@ -1357,6 +1364,8 @@ switch (id) { case 'hold': return { url: '/api/repos/' + seg + '/items/' + n + '/hold', body: { held: true, type } }; case 'release': return { url: '/api/repos/' + seg + '/items/' + n + '/hold', body: { held: false, type } }; + case 'sha-waive': return item.kind === 'pr' ? null : { url: '/api/repos/' + seg + '/items/' + n + '/sha-waiver', body: { waived: true } }; + case 'sha-restore': return item.kind === 'pr' ? null : { url: '/api/repos/' + seg + '/items/' + n + '/sha-waiver', body: { waived: false } }; case 'retry': return { url: '/api/repos/rescan', body: {}, once: true }; case 'wf-dispatch': return { url: '/api/workflows/dispatch', body: { repo: item.repo, number: n } }; case 'needs-human': return { url: '/api/review/pipeline/' + seg + '/' + n + '/send-to-human', body: { reason: payload.comment || ('flagged from the activity monitor for ' + stageTrackerRefOf(item)) } }; @@ -2312,7 +2321,7 @@ function stageTrackerMergeBannerMs() { return stageTrackerToastMs('info') * STAGE_TRACKER_MERGE_BANNER_FACTOR; } const STAGE_TRACKER_ACTING_MAX_MS = 180000; const STAGE_TRACKER_ACTING_CAPTIONS = { - 'hold': 'Holding…', 'release': 'Releasing hold…', 'retry': 'Re-evaluating…', 'wf-dispatch': 'Sending to the agent…', 'needs-human': 'Marking needs-human…', 'accept-triage': 'Accepting triage…', + 'hold': 'Holding…', 'release': 'Releasing hold…', 'sha-waive': 'Waiving SHA requirement…', 'sha-restore': 'Restoring SHA requirement…', 'retry': 'Re-evaluating…', 'wf-dispatch': 'Sending to the agent…', 'needs-human': 'Marking needs-human…', 'accept-triage': 'Accepting triage…', 'blocker:recheck': 'Checking App permissions…', 'blocker:close-partial': 'Closing as partial…', 'decide:delegate': 'Hive deciding…', 'decide:delegate:preview': 'Asking the hive…', 'decide:delegate-all': 'Hive deciding each PR…', 'decide:delegate:rerun': 'Hive deciding again…', 'decide:approve': 'Approving…', 'decide:direction': 'Recording direction…', 'decide:close-superseded': 'Closing…', 'decide:close-wontfix': 'Closing…', 'decide:close-read': 'Closing…', 'decide:close-deferred': 'Closing…', 'decide:close-issue': 'Closing…', 'decide:merge-now': 'Merging…', 'decide:queue-merge': 'Recording approval…', @@ -2322,7 +2331,7 @@ const STAGE_TRACKER_ACTION_WORDS = { adopted: 'adopted', approved: 'approved', dispatched: 'sent to its agent', recommended: 'recommendation only', closed: 'closed', directed: 'direction recorded', refused: 'refused', 'decided-each': 'decided per PR', merged: 'merged', 'queued-for-merge': 'queued for merge — hive merges it on its next pass once CI is green', [STAGE_TRACKER_ACTION_REBASE_QUEUED]: 'rebase queued, merge to follow', - held: 'held', released: 'hold released', 'sentinel-confirmed': 'sentinel confirmed safe', rescanned: 'rescanned', 'triage-accepted': 'triage accepted', 'needs-human': 'marked needs-human', rerouted: 'rerouted', [STAGE_TRACKER_ACTION_NOOP]: 'no change', + held: 'held', released: 'hold released', 'sha-waived': 'SHA requirement waived', 'sha-restored': 'SHA requirement restored', 'sentinel-confirmed': 'sentinel confirmed safe', rescanned: 'rescanned', 'triage-accepted': 'triage accepted', 'needs-human': 'marked needs-human', rerouted: 'rerouted', [STAGE_TRACKER_ACTION_NOOP]: 'no change', [STAGE_TRACKER_ACTION_NO_EFFECT]: 'no effect yet', }; // Once the server has answered, a terminal action's caption says so diff --git a/src/pkg/dashboard/static-src/js/tracker-row-strip.js b/src/pkg/dashboard/static-src/js/tracker-row-strip.js index 9e02bb35e5..be924743bc 100644 --- a/src/pkg/dashboard/static-src/js/tracker-row-strip.js +++ b/src/pkg/dashboard/static-src/js/tracker-row-strip.js @@ -626,7 +626,9 @@ // word, "Waiting on shared CI · #17463" (hivecommons/hive#17500). const incident = sg.detour && sg.number === 30 && remediation === 'deferred' && item.deferral && Number(item.deferral.incident) > 0 && item.deferral.incident_url ? '#' + Number(item.deferral.incident) : ''; const detourText = incident && sg.detour.text.indexOf(incident) >= 0 ? esc(sg.detour.text).replace(esc(incident), `${esc(incident)}`) : (sg.detour ? esc(sg.detour.text) : ''); - const word = sg.detour ? `${detourText}${detourHolder}${reasonHtml}` : (gateWord || `${esc(sg.short)}${progressHolderHtml}${reasonHtml}`); + // A held / waived SHA requirement rides the lit chevron as a note (#18866). + const shaHoldNote = active && !sg.cap && !sg.detour && !gateWord && typeof stageTrackerSHAHoldNoteHtml === 'function' ? stageTrackerSHAHoldNoteHtml(item) : ''; + const word = sg.detour ? `${detourText}${detourHolder}${reasonHtml}` : (gateWord || `${esc(sg.short)}${progressHolderHtml}${reasonHtml}${shaHoldNote}`); const gateCue = gateWord && typeof stageTrackerGateCueHtml === 'function' ? stageTrackerGateCueHtml(item, nowMs, trains) : ''; // The agent-working spinner (tracker-cues) names the agent and what // it did, so a spinning glyph is never unexplained. @@ -636,9 +638,12 @@ // the column is the row's history and wears the history mark. if (sg.cap) inner = sg.terminal ? stageTrackerIcon(sg.number, 'ham-ico') : stageTrackerIcon('history', 'ham-ico ham-history-ico', 'History — no decisions or actions recorded yet'); else if (active) { + const shaHold = typeof stageTrackerSHAHoldOf === 'function' ? stageTrackerSHAHoldOf(item) : null; + const shaHoldTip = shaHold ? shaHold.pill + ' — ' + shaHold.tip : ''; const fullTip = [tip, gateCaption || (sg.detour ? sg.detour.text : sg.short + (progressActor ? ' · ' + progressActor.who : '')), item.caption, item.reason, item.head ? 'head ' + item.head : '', - item.hold ? (item.hold.pill || 'Held by @' + item.hold.by) + (item.hold.reason ? ' · ' + item.hold.reason : '') : ''].filter(Boolean).join(' · '); + item.hold ? (item.hold.pill || 'Held by @' + item.hold.by) + (item.hold.reason ? ' · ' + item.hold.reason : '') : '', + shaHoldTip].filter(Boolean).join(' · '); const tipID = 'ham-chevron-tip-' + [item.repo || '', item.kind || '', item.number || 0, sg.number].map(x => encodeURIComponent(String(x))).join('-'); const caption = gateWord || word; const text = decision ? stageTrackerDecisionTriggerHtml(decision, caption, fullTip) : caption; @@ -943,6 +948,26 @@ const who = h.by === 'hive' ? 'hive' : '@' + h.by; return 'Held by ' + who + (h.reason ? ' · ' + h.reason : ''); } + // Pure: the row's SHA-hold state (hivecommons/hive#18866) — `needs-sha` + // held, or `sha-waived` by a maintainer — as the server sends it in + // `sha_hold` ({state, pill, tip, note, by}); null for a PR or no state. + function stageTrackerSHAHoldOf(item) { + const h = item && item.kind === 'issue' ? item.sha_hold : null; + return h && (h.state === 'held' || h.state === 'waived') && h.pill ? h : null; + } + // The visible pill: "Held: needs commit SHA" / "SHA waived by ", + // its hover saying how to lift (post a SHA, or waive) or restore. + function stageTrackerSHAHoldChipHtml(item) { + const h = stageTrackerSHAHoldOf(item); + if (!h) return ''; + const label = String(h.pill) + (h.tip ? ' — ' + h.tip : ''); + return `${esc(h.pill)}`; + } + // The note on the lit Open chevron, beside the stage word. + function stageTrackerSHAHoldNoteHtml(item) { + const h = stageTrackerSHAHoldOf(item); + return h && h.note ? ` · ${esc(h.note)}` : ''; + } // Pure: the hold pill's hover text — who, why, since when. function stageTrackerHoldTip(item, nowMs) { const h = item && item.hold; @@ -976,7 +1001,7 @@ // sentinel / hold / needs-human reasons itself — those chips step aside. const gated = !!(opts && opts.gate); // The informational notice is not a gate reason, so its chip stays. - const sentinel = (gated && !item.sentinel_notice ? '' : stageTrackerSentinelChipHtml(item)) + (typeof stageTrackerPreparationChipHtml === 'function' ? stageTrackerPreparationChipHtml(item) : '') + (typeof stageTrackerAdoptionChipHtml === 'function' ? stageTrackerAdoptionChipHtml(item) : '') + (typeof stageTrackerPresenceChipHtml === 'function' ? stageTrackerPresenceChipHtml(item) : '') + (typeof stageTrackerPushChipHtml === 'function' ? stageTrackerPushChipHtml(item, Date.now()) : '') + (typeof stageTrackerReroutePillHtml === 'function' ? stageTrackerReroutePillHtml(item) : '') + (typeof stageTrackerSupersedesChipHtml === 'function' ? stageTrackerSupersedesChipHtml(item, Date.now()) : '') + (typeof stageTrackerOverlapBadgeHtml === 'function' ? stageTrackerOverlapBadgeHtml(item) : ''); + const sentinel = (gated && !item.sentinel_notice ? '' : stageTrackerSentinelChipHtml(item)) + (typeof stageTrackerPreparationChipHtml === 'function' ? stageTrackerPreparationChipHtml(item) : '') + (typeof stageTrackerAdoptionChipHtml === 'function' ? stageTrackerAdoptionChipHtml(item) : '') + (typeof stageTrackerPresenceChipHtml === 'function' ? stageTrackerPresenceChipHtml(item) : '') + (typeof stageTrackerPushChipHtml === 'function' ? stageTrackerPushChipHtml(item, Date.now()) : '') + (typeof stageTrackerReroutePillHtml === 'function' ? stageTrackerReroutePillHtml(item) : '') + (typeof stageTrackerSupersedesChipHtml === 'function' ? stageTrackerSupersedesChipHtml(item, Date.now()) : '') + (typeof stageTrackerOverlapBadgeHtml === 'function' ? stageTrackerOverlapBadgeHtml(item) : '') + (typeof stageTrackerSHAHoldChipHtml === 'function' ? stageTrackerSHAHoldChipHtml(item) : ''); const mods = (Array.isArray(item.modifiers) ? item.modifiers.slice() : []) .filter(m => !gated || STAGE_TRACKER_GATE_MODS.indexOf(m) < 0) .sort((x, y) => STAGE_TRACKER_MOD_PRIORITY.indexOf(x) - STAGE_TRACKER_MOD_PRIORITY.indexOf(y)); diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index 3003d66cef..7d016ea268 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -1717,6 +1717,8 @@ rides last; past dashboard.stage_tracker.waiting_push_stale_h it takes the muted warning tone. "@zoe pushed abc1234 · 2m" links to the commit. */ .ham-push-stale { color: color-mix(in srgb, var(--status-warn) 70%, var(--text-faint)); } + .ham-badge-sha-hold { color: var(--status-warn); border-color: color-mix(in srgb, var(--status-warn) 55%, transparent); } + .ham-badge-sha-hold.ham-sha-waived { color: var(--text-muted); border-color: color-mix(in srgb, var(--text-muted) 45%, transparent); } .ham-badge-push { text-decoration: none; } .ham-badge-push:hover { color: var(--text-muted); } /* Presence indicator on a waiting-on pill (hive PR 15051): who the row @@ -20396,7 +20398,9 @@

Where to get help

// word, "Waiting on shared CI · #17463" (hivecommons/hive#17500). const incident = sg.detour && sg.number === 30 && remediation === 'deferred' && item.deferral && Number(item.deferral.incident) > 0 && item.deferral.incident_url ? '#' + Number(item.deferral.incident) : ''; const detourText = incident && sg.detour.text.indexOf(incident) >= 0 ? esc(sg.detour.text).replace(esc(incident), `${esc(incident)}`) : (sg.detour ? esc(sg.detour.text) : ''); - const word = sg.detour ? `${detourText}${detourHolder}${reasonHtml}` : (gateWord || `${esc(sg.short)}${progressHolderHtml}${reasonHtml}`); + // A held / waived SHA requirement rides the lit chevron as a note (#18866). + const shaHoldNote = active && !sg.cap && !sg.detour && !gateWord && typeof stageTrackerSHAHoldNoteHtml === 'function' ? stageTrackerSHAHoldNoteHtml(item) : ''; + const word = sg.detour ? `${detourText}${detourHolder}${reasonHtml}` : (gateWord || `${esc(sg.short)}${progressHolderHtml}${reasonHtml}${shaHoldNote}`); const gateCue = gateWord && typeof stageTrackerGateCueHtml === 'function' ? stageTrackerGateCueHtml(item, nowMs, trains) : ''; // The agent-working spinner (tracker-cues) names the agent and what // it did, so a spinning glyph is never unexplained. @@ -20406,9 +20410,12 @@

Where to get help

// the column is the row's history and wears the history mark. if (sg.cap) inner = sg.terminal ? stageTrackerIcon(sg.number, 'ham-ico') : stageTrackerIcon('history', 'ham-ico ham-history-ico', 'History — no decisions or actions recorded yet'); else if (active) { + const shaHold = typeof stageTrackerSHAHoldOf === 'function' ? stageTrackerSHAHoldOf(item) : null; + const shaHoldTip = shaHold ? shaHold.pill + ' — ' + shaHold.tip : ''; const fullTip = [tip, gateCaption || (sg.detour ? sg.detour.text : sg.short + (progressActor ? ' · ' + progressActor.who : '')), item.caption, item.reason, item.head ? 'head ' + item.head : '', - item.hold ? (item.hold.pill || 'Held by @' + item.hold.by) + (item.hold.reason ? ' · ' + item.hold.reason : '') : ''].filter(Boolean).join(' · '); + item.hold ? (item.hold.pill || 'Held by @' + item.hold.by) + (item.hold.reason ? ' · ' + item.hold.reason : '') : '', + shaHoldTip].filter(Boolean).join(' · '); const tipID = 'ham-chevron-tip-' + [item.repo || '', item.kind || '', item.number || 0, sg.number].map(x => encodeURIComponent(String(x))).join('-'); const caption = gateWord || word; const text = decision ? stageTrackerDecisionTriggerHtml(decision, caption, fullTip) : caption; @@ -20713,6 +20720,26 @@

Where to get help

const who = h.by === 'hive' ? 'hive' : '@' + h.by; return 'Held by ' + who + (h.reason ? ' · ' + h.reason : ''); } + // Pure: the row's SHA-hold state (hivecommons/hive#18866) — `needs-sha` + // held, or `sha-waived` by a maintainer — as the server sends it in + // `sha_hold` ({state, pill, tip, note, by}); null for a PR or no state. + function stageTrackerSHAHoldOf(item) { + const h = item && item.kind === 'issue' ? item.sha_hold : null; + return h && (h.state === 'held' || h.state === 'waived') && h.pill ? h : null; + } + // The visible pill: "Held: needs commit SHA" / "SHA waived by ", + // its hover saying how to lift (post a SHA, or waive) or restore. + function stageTrackerSHAHoldChipHtml(item) { + const h = stageTrackerSHAHoldOf(item); + if (!h) return ''; + const label = String(h.pill) + (h.tip ? ' — ' + h.tip : ''); + return `${esc(h.pill)}`; + } + // The note on the lit Open chevron, beside the stage word. + function stageTrackerSHAHoldNoteHtml(item) { + const h = stageTrackerSHAHoldOf(item); + return h && h.note ? ` · ${esc(h.note)}` : ''; + } // Pure: the hold pill's hover text — who, why, since when. function stageTrackerHoldTip(item, nowMs) { const h = item && item.hold; @@ -20746,7 +20773,7 @@

Where to get help

// sentinel / hold / needs-human reasons itself — those chips step aside. const gated = !!(opts && opts.gate); // The informational notice is not a gate reason, so its chip stays. - const sentinel = (gated && !item.sentinel_notice ? '' : stageTrackerSentinelChipHtml(item)) + (typeof stageTrackerPreparationChipHtml === 'function' ? stageTrackerPreparationChipHtml(item) : '') + (typeof stageTrackerAdoptionChipHtml === 'function' ? stageTrackerAdoptionChipHtml(item) : '') + (typeof stageTrackerPresenceChipHtml === 'function' ? stageTrackerPresenceChipHtml(item) : '') + (typeof stageTrackerPushChipHtml === 'function' ? stageTrackerPushChipHtml(item, Date.now()) : '') + (typeof stageTrackerReroutePillHtml === 'function' ? stageTrackerReroutePillHtml(item) : '') + (typeof stageTrackerSupersedesChipHtml === 'function' ? stageTrackerSupersedesChipHtml(item, Date.now()) : '') + (typeof stageTrackerOverlapBadgeHtml === 'function' ? stageTrackerOverlapBadgeHtml(item) : ''); + const sentinel = (gated && !item.sentinel_notice ? '' : stageTrackerSentinelChipHtml(item)) + (typeof stageTrackerPreparationChipHtml === 'function' ? stageTrackerPreparationChipHtml(item) : '') + (typeof stageTrackerAdoptionChipHtml === 'function' ? stageTrackerAdoptionChipHtml(item) : '') + (typeof stageTrackerPresenceChipHtml === 'function' ? stageTrackerPresenceChipHtml(item) : '') + (typeof stageTrackerPushChipHtml === 'function' ? stageTrackerPushChipHtml(item, Date.now()) : '') + (typeof stageTrackerReroutePillHtml === 'function' ? stageTrackerReroutePillHtml(item) : '') + (typeof stageTrackerSupersedesChipHtml === 'function' ? stageTrackerSupersedesChipHtml(item, Date.now()) : '') + (typeof stageTrackerOverlapBadgeHtml === 'function' ? stageTrackerOverlapBadgeHtml(item) : '') + (typeof stageTrackerSHAHoldChipHtml === 'function' ? stageTrackerSHAHoldChipHtml(item) : ''); const mods = (Array.isArray(item.modifiers) ? item.modifiers.slice() : []) .filter(m => !gated || STAGE_TRACKER_GATE_MODS.indexOf(m) < 0) .sort((x, y) => STAGE_TRACKER_MOD_PRIORITY.indexOf(x) - STAGE_TRACKER_MOD_PRIORITY.indexOf(y)); @@ -25226,7 +25253,7 @@

All labels

// is not generic: a row offers it either from the nudge (`adoption`) // or as a server decision option (a contributor PR's DCO / fixer // exhaustion, where it replaced "re-author"), never both. - const STAGE_TRACKER_GENERIC_ACTIONS = ['hold', 'release', 'retry', 'needs-human', 'accept-triage', 'open', 'copy', 'decide:delegate', 'decide:delegate-all', 'decide:close-issue']; + const STAGE_TRACKER_GENERIC_ACTIONS = ['hold', 'release', 'sha-waive', 'sha-restore', 'retry', 'needs-human', 'accept-triage', 'open', 'copy', 'decide:delegate', 'decide:delegate-all', 'decide:close-issue']; const _stageTrackerCloseIssueBusy = new Set(); // Accept triage shows on an issue the chevron calls "Triage needed": // stage 015, or the needs-triage pill on a pre-claim stage (010 / 017 / @@ -25674,6 +25701,13 @@

All labels

out.push(has('hold') ? { id: 'release', label: 'Release hold', enabled: write, why: write ? '' : STAGE_TRACKER_WHY_WRITE, sep: triage && !target } : { id: 'hold', label: 'Hold', enabled: write, why: write ? '' : STAGE_TRACKER_WHY_WRITE, sep: triage && !target }); + // A SHA-held issue (needs-sha) offers the override next to the hold + // actions: Waive SHA requirement, then Restore once it is waived + // (hivecommons/hive#18866). Same roles as releasing a hold. + const shaHold = typeof stageTrackerSHAHoldOf === 'function' ? stageTrackerSHAHoldOf(item) : null; + if (shaHold) out.push(shaHold.state === 'waived' + ? { id: 'sha-restore', label: 'Restore SHA requirement', enabled: write, why: write ? '' : STAGE_TRACKER_WHY_WRITE } + : { id: 'sha-waive', label: 'Waive SHA requirement', hint: 'hive works it without a SHA', enabled: write, why: write ? '' : STAGE_TRACKER_WHY_WRITE }); out.push({ id: 'retry', label: 'Re-evaluate now', hint: 'rescan', enabled: true, why: '' }); // A model-bound row whose state the model hands to an agent profile // (cncf/techdocs#395): the owner can send it now. @@ -26526,6 +26560,8 @@

All labels

switch (id) { case 'hold': return { url: '/api/repos/' + seg + '/items/' + n + '/hold', body: { held: true, type } }; case 'release': return { url: '/api/repos/' + seg + '/items/' + n + '/hold', body: { held: false, type } }; + case 'sha-waive': return item.kind === 'pr' ? null : { url: '/api/repos/' + seg + '/items/' + n + '/sha-waiver', body: { waived: true } }; + case 'sha-restore': return item.kind === 'pr' ? null : { url: '/api/repos/' + seg + '/items/' + n + '/sha-waiver', body: { waived: false } }; case 'retry': return { url: '/api/repos/rescan', body: {}, once: true }; case 'wf-dispatch': return { url: '/api/workflows/dispatch', body: { repo: item.repo, number: n } }; case 'needs-human': return { url: '/api/review/pipeline/' + seg + '/' + n + '/send-to-human', body: { reason: payload.comment || ('flagged from the activity monitor for ' + stageTrackerRefOf(item)) } }; @@ -27481,7 +27517,7 @@

All labels

function stageTrackerMergeBannerMs() { return stageTrackerToastMs('info') * STAGE_TRACKER_MERGE_BANNER_FACTOR; } const STAGE_TRACKER_ACTING_MAX_MS = 180000; const STAGE_TRACKER_ACTING_CAPTIONS = { - 'hold': 'Holding…', 'release': 'Releasing hold…', 'retry': 'Re-evaluating…', 'wf-dispatch': 'Sending to the agent…', 'needs-human': 'Marking needs-human…', 'accept-triage': 'Accepting triage…', + 'hold': 'Holding…', 'release': 'Releasing hold…', 'sha-waive': 'Waiving SHA requirement…', 'sha-restore': 'Restoring SHA requirement…', 'retry': 'Re-evaluating…', 'wf-dispatch': 'Sending to the agent…', 'needs-human': 'Marking needs-human…', 'accept-triage': 'Accepting triage…', 'blocker:recheck': 'Checking App permissions…', 'blocker:close-partial': 'Closing as partial…', 'decide:delegate': 'Hive deciding…', 'decide:delegate:preview': 'Asking the hive…', 'decide:delegate-all': 'Hive deciding each PR…', 'decide:delegate:rerun': 'Hive deciding again…', 'decide:approve': 'Approving…', 'decide:direction': 'Recording direction…', 'decide:close-superseded': 'Closing…', 'decide:close-wontfix': 'Closing…', 'decide:close-read': 'Closing…', 'decide:close-deferred': 'Closing…', 'decide:close-issue': 'Closing…', 'decide:merge-now': 'Merging…', 'decide:queue-merge': 'Recording approval…', @@ -27491,7 +27527,7 @@

All labels

const STAGE_TRACKER_ACTION_WORDS = { adopted: 'adopted', approved: 'approved', dispatched: 'sent to its agent', recommended: 'recommendation only', closed: 'closed', directed: 'direction recorded', refused: 'refused', 'decided-each': 'decided per PR', merged: 'merged', 'queued-for-merge': 'queued for merge — hive merges it on its next pass once CI is green', [STAGE_TRACKER_ACTION_REBASE_QUEUED]: 'rebase queued, merge to follow', - held: 'held', released: 'hold released', 'sentinel-confirmed': 'sentinel confirmed safe', rescanned: 'rescanned', 'triage-accepted': 'triage accepted', 'needs-human': 'marked needs-human', rerouted: 'rerouted', [STAGE_TRACKER_ACTION_NOOP]: 'no change', + held: 'held', released: 'hold released', 'sha-waived': 'SHA requirement waived', 'sha-restored': 'SHA requirement restored', 'sentinel-confirmed': 'sentinel confirmed safe', rescanned: 'rescanned', 'triage-accepted': 'triage accepted', 'needs-human': 'marked needs-human', rerouted: 'rerouted', [STAGE_TRACKER_ACTION_NOOP]: 'no change', [STAGE_TRACKER_ACTION_NO_EFFECT]: 'no effect yet', }; // Once the server has answered, a terminal action's caption says so diff --git a/src/pkg/github/client.go b/src/pkg/github/client.go index 54ebd8ee27..7b65b65cf1 100644 --- a/src/pkg/github/client.go +++ b/src/pkg/github/client.go @@ -10,6 +10,7 @@ import ( "net/url" "os" "regexp" + "slices" "sort" "strconv" "strings" @@ -149,6 +150,10 @@ type Client struct { // needsSHALabelName is the configured SHA-hold label, recorded by each // EnforceSHAHold sweep (guarded by issueFilterMu). Empty means the default. needsSHALabelName string + // shaWaivers records who waived the SHA requirement per repo#number + // (hivecommons/hive#18866); guarded by shaWaiversMu. + shaWaiversMu sync.Mutex + shaWaivers map[string]string // reporterConfirmationEnabled restores the legacy close gate for all // human-filed bug-family issues when configured. Nil/false means only // per-issue opt-in markers activate the gate. @@ -4764,6 +4769,11 @@ const NeedsSHALabelDescription = "Waiting on the reporter for the commit SHA; hi // name, or the default name), or "" when none. An issue wearing it is parked // on the reporter and kept out of agent work lanes. func (c *Client) needsSHALabelOn(labels []string) string { + // A maintainer's waiver (hivecommons/hive#18866) outranks a lingering + // needs-sha until the sweep removes it. + if labelPresent(labels, SHAWaivedLabel) { + return "" + } c.issueFilterMu.RLock() configured := c.needsSHALabelName c.issueFilterMu.RUnlock() @@ -4835,14 +4845,53 @@ func (c *Client) EnforceSHAHold(ctx context.Context, cfg SHAHoldConfig) (*SHAHol } author := safeGetLogin(issue.GetUser()) - if author == cfg.AIAuthor || isInternalAuthor(author, cfg.InternalAuthors) { - result.Skipped++ - continue - } - labels := extractLabels(issue.Labels) held := c.isHeld(labels) - hasSHA := shaPattern.MatchString(issue.GetBody()) + + // Not every reporter owes a SHA (hivecommons/hive#18866): the hive's + // own accounts, the project's owners and maintainers, issues whose + // body already names concrete repo paths, and issues a maintainer + // waived are exempt. An exempt issue goes through the same lift path + // as one that gained a SHA, so a needs-sha applied before the + // exemption existed (or before the waiver) is released on this sweep. + exempt := author == cfg.AIAuthor || isInternalAuthor(author, cfg.InternalAuthors) + reason := shaExemptInternal + if !exempt { + reason = cfg.shaHoldExempt(issue.GetAuthorAssociation(), issue.GetBody(), labels) + exempt = reason != "" + } + if labelPresent(labels, SHAWaivedLabel) { + // Read the comments once per waiver, not on every sweep. + if !c.shaWaiverKnown(owner+"/"+repo, issue.GetNumber()) { + c.refreshSHAWaiver(ctx, owner, repo, issue.GetNumber()) + } + } else { + c.RecordSHAWaiver(owner+"/"+repo, issue.GetNumber(), "") + } + hasSHA := exempt || shaPattern.MatchString(issue.GetBody()) + if exempt && reason != shaExemptInternal { + c.logger.Debug("SHA-HOLD exempt", "repo", repo, "issue", issue.GetNumber(), "reason", reason) + } + + if exempt { + // Lift the soft label whatever else is on the issue (a person's + // `hold` included), so a needs-sha applied before the exemption + // or the waiver existed is released on this sweep. + soft := cfg.shaHoldLabel() + softHeld := labelPresent(labels, soft) + if softHeld { + c.enforceSoftSHAHold(ctx, owner, repo, issue.GetNumber(), author, soft, labels, false, true, result) + labels = slices.DeleteFunc(slices.Clone(labels), func(l string) bool { return strings.EqualFold(strings.TrimSpace(l), strings.TrimSpace(soft)) }) + } + // A `hold` the sweep itself applied before #18468 is still + // lifted by the path below; a person's hold is left alone there. + if !held { + if !softHeld { + result.Skipped++ + } + continue + } + } if !hasSHA { hasSHA = c.checkCommentsForSHA(ctx, owner, repo, issue.GetNumber(), author) diff --git a/src/pkg/github/notification_write_sites.go b/src/pkg/github/notification_write_sites.go index e09daf832a..1ff60465ec 100644 --- a/src/pkg/github/notification_write_sites.go +++ b/src/pkg/github/notification_write_sites.go @@ -45,6 +45,7 @@ var notificationWriteSites = map[string]NotificationWriteSite{ "dashboard.(*Server).handleRepoItemBlockerClosePartial": {Class: NotificationClassStatus}, "dashboard.(*Server).handleRepoItemDecision": {Class: NotificationClassStatus}, "dashboard.(*Server).handleRepoItemSentinelConfirm": {Class: NotificationClassStatus}, + "dashboard.(*Server).handleRepoItemSHAWaiver": {Class: NotificationClassStatus}, "dashboard.(*Server).handleReviewQueueSupersededClose": {Class: NotificationClassStatus}, "dashboard.(*Server).mirrorPlanWith": {Class: NotificationClassStatus}, "github.(*Client).CloseIssueForConfiguredLinePR": {Class: NotificationClassStatus}, diff --git a/src/pkg/github/sha_hold_exempt.go b/src/pkg/github/sha_hold_exempt.go new file mode 100644 index 0000000000..a9e10306c2 --- /dev/null +++ b/src/pkg/github/sha_hold_exempt.go @@ -0,0 +1,188 @@ +package github + +import ( + "context" + "regexp" + "strconv" + "strings" +) + +// The SHA-hold gate exists to get a reproducible build out of an outside +// reporter. It is not meant for the project's own people or for a report that +// already points at the code (hivecommons/hive#18866), and an operator can +// waive it for one issue. + +// SHAWaivedLabel is the persistent override: while it is on an issue the SHA +// sweep neither applies nor keeps `needs-sha`. It is applied (and removed) by +// the dashboard's "Waive SHA requirement" row action, which is gated to the +// same roles as releasing a `hold`; a person can also add it by hand. +const SHAWaivedLabel = "sha-waived" + +// SHAWaivedLabelDescription is the repo label description for SHAWaivedLabel. +const SHAWaivedLabelDescription = "A maintainer waived the commit-SHA requirement; hive will not hold this issue for a SHA." + +const shaWaivedMarkerPrefix = "" + +// SHAWaivedMarker is the hidden marker on the App-authored comment that +// records who waived the requirement. +func SHAWaivedMarker(login string) string { + return shaWaivedMarkerPrefix + strings.TrimSpace(login) + shaWaivedMarkerSuffix +} + +// shaWaivedBy returns the login named by a waiver marker in body, or "". +func shaWaivedBy(body string) string { + i := strings.Index(body, shaWaivedMarkerPrefix) + if i < 0 { + return "" + } + rest := body[i+len(shaWaivedMarkerPrefix):] + j := strings.Index(rest, shaWaivedMarkerSuffix) + if j < 0 { + return "" + } + return strings.TrimSpace(rest[:j]) +} + +// Reasons shaHoldExempt (and the sweep, for the hive's own accounts) give. +const ( + shaExemptInternal = "internal-author" + shaExemptWaived = "waived" + shaExemptMaintainer = "maintainer-authored" + shaExemptCodePaths = "names-code-paths" +) + +// defaultSHAExemptAssociations are the author associations treated as the +// project's own people when the caller passes none. +var defaultSHAExemptAssociations = []string{"OWNER", "MEMBER", "COLLABORATOR"} + +// repoPathTopDirs are the repository's top-level directories a path must +// start with to count as a concrete code path. +const repoPathTopDirs = `\.github|src|pkg|cmd|internal|docs|bin|config|dashboard|examples|systemd|launchd|githooks` + +// repoPathExtensions are the file extensions a code path may end in. +const repoPathExtensions = `go|js|ts|tsx|jsx|py|sh|yaml|yml|json|toml|md|html|css|sql|mod` + +// concreteRepoPathPattern matches a repo-relative file path such as +// `src/pkg/github/client.go`: a known top-level directory, one or more +// segments, a known extension, delimited by whitespace or punctuation (so a +// URL or an absolute path like /usr/lib/x.py never matches). +var concreteRepoPathPattern = regexp.MustCompile( + "(?:^|[\\s`'\"(\\[<])(?:" + repoPathTopDirs + ")/[A-Za-z0-9_./-]*[A-Za-z0-9_-]\\.(?:" + repoPathExtensions + ")(?:[\\s`'\")\\]>:,.;]|$)") + +// bodyNamesRepoPaths reports whether an issue body names at least one +// concrete repository file path. It deliberately ignores comments and +// bare file names: a reporter who cites src/... has read the code. The +// signal is self-attested: the text is only pattern-matched and the path is +// never checked to exist, so any reporter can write one to skip the gate. +// That is accepted by design (hivecommons/hive#18866). +func bodyNamesRepoPaths(body string) bool { + return concreteRepoPathPattern.MatchString(body) +} + +// shaHoldExempt reports why the sweep does not gate an issue on a SHA: "" when +// it is gated, else a short reason for the log. Internal authors are handled +// by the caller. +func (cfg SHAHoldConfig) shaHoldExempt(association, body string, labels []string) string { + switch { + case labelPresent(labels, SHAWaivedLabel): + return shaExemptWaived + case cfg.trustedAssociation(association): + return shaExemptMaintainer + case bodyNamesRepoPaths(body): + return shaExemptCodePaths + } + return "" +} + +func (cfg SHAHoldConfig) trustedAssociation(association string) bool { + association = strings.TrimSpace(association) + if association == "" { + return false + } + set := cfg.TrustedAssociations + if len(set) == 0 { + set = defaultSHAExemptAssociations + } + for _, a := range set { + if strings.EqualFold(strings.TrimSpace(a), association) { + return true + } + } + return false +} + +// SHAWaivedBy returns who waived the SHA requirement on repo#number, as the +// sweep last read it from the App-authored waiver comment (or as the +// dashboard recorded it), or "". +func (c *Client) SHAWaivedBy(repo string, number int) string { + if c == nil { + return "" + } + c.shaWaiversMu.Lock() + defer c.shaWaiversMu.Unlock() + if by := c.shaWaivers[shaWaiverKey(repo, number)]; by != shaWaiverUnattributed { + return by + } + return "" +} + +// shaWaiverUnattributed marks a waived issue whose waiver comment was read +// and carries no marker (a label added by hand), so the sweep does not list +// its comments again every tick. +const shaWaiverUnattributed = "?" + +// shaWaiverKnown reports whether the sweep already resolved who waived the +// issue (or that nobody is named). +func (c *Client) shaWaiverKnown(repo string, number int) bool { + c.shaWaiversMu.Lock() + defer c.shaWaiversMu.Unlock() + _, ok := c.shaWaivers[shaWaiverKey(repo, number)] + return ok +} + +// RecordSHAWaiver remembers who waived the requirement; an empty login +// forgets it. +func (c *Client) RecordSHAWaiver(repo string, number int, login string) { + if c == nil { + return + } + key := shaWaiverKey(repo, number) + c.shaWaiversMu.Lock() + defer c.shaWaiversMu.Unlock() + if strings.TrimSpace(login) == "" { + delete(c.shaWaivers, key) + return + } + if c.shaWaivers == nil { + c.shaWaivers = map[string]string{} + } + c.shaWaivers[key] = strings.TrimSpace(login) +} + +func shaWaiverKey(repo string, number int) string { + return strings.ToLower(strings.TrimSpace(repo)) + "#" + strconv.Itoa(number) +} + +// refreshSHAWaiver reads the newest App-authored waiver comment so the +// dashboard can name who waived the requirement after a restart. +func (c *Client) refreshSHAWaiver(ctx context.Context, owner, repo string, number int) { + key := owner + "/" + repo + comments, err := c.listIssueComments(ctx, owner, repo, number) + if err != nil { + return + } + by := "" + for _, comment := range comments { + if comment == nil || !c.isTrustedAppBotCommentAuthor(comment) { + continue + } + if who := shaWaivedBy(comment.GetBody()); who != "" { + by = who + } + } + if by == "" { + by = shaWaiverUnattributed + } + c.RecordSHAWaiver(key, number, by) +} diff --git a/src/pkg/github/sha_hold_exempt_test.go b/src/pkg/github/sha_hold_exempt_test.go new file mode 100644 index 0000000000..9655e6af10 --- /dev/null +++ b/src/pkg/github/sha_hold_exempt_test.go @@ -0,0 +1,180 @@ +package github + +import ( + "context" + "fmt" + "net/http/httptest" + "strings" + "testing" +) + +// hivecommons/hive#18866: the SHA-hold gate is for outside reporters. These +// tests assert the invariant both ways: an external bug with neither a SHA +// nor code paths is still held, while owner-filed and detailed-body issues +// are not, a needs-sha applied before the exemption is lifted, and a +// maintainer's waiver persists across sweeps. + +const detailedBody = "The sweep drops the label: see src/pkg/github/client.go and `src/pkg/dashboard/stage_tracker.go`." + +func runSHASweep(t *testing.T, issue wireIssue, comments []wireComment, rec *shaSoftRecorder) *SHAHoldResult { + t.Helper() + org, repo := "testorg", "console" + server := httptest.NewServer(buildSHASoftMux(t, org, repo, issue, comments, nil, rec)) + t.Cleanup(server.Close) + c := newTestClient(t, server, org, []string{repo}) + c.SetAppBotLogin(testHiveAppBotLogin) + got, err := c.EnforceSHAHold(context.Background(), SHAHoldConfig{PrimaryRepo: repo, AIAuthor: "hive-bot", TrustedLabel: "needs-sha"}) + if err != nil { + t.Fatalf("EnforceSHAHold: %v", err) + } + return got +} + +func TestEnforceSHAHold_ExemptionInvariant(t *testing.T) { + cases := []struct { + name string + author string + association string + body string + labels []string + wantHeld bool + wantRemoved []string + }{ + {name: "external bug without SHA or paths is still held", author: "stranger", association: "NONE", body: "it crashes on startup", wantHeld: true}, + {name: "external bug citing an absolute path is still held", author: "stranger", association: "CONTRIBUTOR", body: "see /usr/lib/python3/site.py line 4 and https://example.com/src/app.go", wantHeld: true}, + {name: "owner-filed bug is not held", author: "owner", association: "OWNER", body: "it crashes on startup"}, + {name: "collaborator-filed bug is not held", author: "colab", association: "COLLABORATOR", body: "it crashes"}, + {name: "detailed external body naming repo paths is not held", author: "stranger", association: "NONE", body: detailedBody}, + {name: "hive's own bot-filed bug is not held", author: "hivecommons-hive[bot]", association: "NONE", body: "it crashes"}, + {name: "needs-sha already on an owner-filed bug is lifted", author: "owner", association: "OWNER", body: "x", labels: []string{"needs-sha"}, wantRemoved: []string{"needs-sha"}}, + {name: "needs-sha already on a detailed-body bug is lifted", author: "stranger", association: "NONE", body: detailedBody, labels: []string{"needs-sha"}, wantRemoved: []string{"needs-sha"}}, + {name: "needs-sha on an external bug without SHA stays", author: "stranger", association: "NONE", body: "it crashes", labels: []string{"needs-sha"}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + labels := []wireLabel{{Name: "kind/bug"}} + for _, l := range tc.labels { + labels = append(labels, wireLabel{Name: l}) + } + rec := &shaSoftRecorder{} + issue := wireIssue{Number: 18740, Title: "bug", User: wireUser{tc.author}, Labels: labels, Body: tc.body, CreatedAt: hoursAgo(11), AuthorAssociation: tc.association} + runSHASweep(t, issue, nil, rec) + if gotHeld := len(rec.added) > 0; gotHeld != tc.wantHeld { + t.Errorf("added = %v, want held=%v", rec.added, tc.wantHeld) + } + if fmt.Sprint(rec.removed) != fmt.Sprint(tc.wantRemoved) { + t.Errorf("removed = %v, want %v", rec.removed, tc.wantRemoved) + } + }) + } +} + +func TestBodyNamesRepoPaths(t *testing.T) { + yes := []string{ + "src/pkg/github/client.go", + "broken in `src/pkg/dashboard/static-src/js/tracker-row-strip.js`, line 12", + "(see docs/labels-and-control-signals/reference.md)", + "edit .github/workflows/ci.yml:3", + "first line\nsrc/cmd/hive/main.go.", + } + no := []string{ + "", + "it crashes", + "client.go is wrong", + "/usr/local/src/pkg/foo.go", + "https://example.com/src/app.go", + "src/pkg/github", + "mysrc/pkg/x.go", + "see node_modules/x/index.js", + } + for _, b := range yes { + if !bodyNamesRepoPaths(b) { + t.Errorf("want a path in %q", b) + } + } + for _, b := range no { + if bodyNamesRepoPaths(b) { + t.Errorf("want no path in %q", b) + } + } +} + +// A waiver persists: the sweep neither re-adds needs-sha across repeated +// sweeps nor leaves a lingering one on the issue. +func TestEnforceSHAHold_WaiverPersistsAcrossSweeps(t *testing.T) { + rec := &shaSoftRecorder{} + issue := wireIssue{Number: 7, Title: "bug", User: wireUser{"stranger"}, Body: "it crashes", CreatedAt: hoursAgo(5), AuthorAssociation: "NONE", + Labels: []wireLabel{{Name: "kind/bug"}, {Name: SHAWaivedLabel}}} + for i := 0; i < 3; i++ { + runSHASweep(t, issue, nil, rec) + } + if len(rec.added) != 0 { + t.Fatalf("a waived issue was re-held: added = %v", rec.added) + } + // A needs-sha left behind by the override race is lifted. + rec2 := &shaSoftRecorder{} + issue.Labels = append(issue.Labels, wireLabel{Name: "needs-sha"}) + runSHASweep(t, issue, nil, rec2) + if fmt.Sprint(rec2.removed) != "[needs-sha]" || len(rec2.added) != 0 { + t.Fatalf("lingering needs-sha: added=%v removed=%v, want it removed", rec2.added, rec2.removed) + } + // Restoring the requirement (label gone) holds it again. + rec3 := &shaSoftRecorder{} + issue.Labels = []wireLabel{{Name: "kind/bug"}} + runSHASweep(t, issue, nil, rec3) + if fmt.Sprint(rec3.added) != "[needs-sha]" { + t.Fatalf("restored requirement: added = %v, want needs-sha", rec3.added) + } +} + +func TestSHAWaivedByReadsAppAuthoredMarker(t *testing.T) { + rec := &shaSoftRecorder{} + issue := wireIssue{Number: 7, Title: "bug", User: wireUser{"stranger"}, Body: "x", CreatedAt: hoursAgo(5), + Labels: []wireLabel{{Name: "kind/bug"}, {Name: SHAWaivedLabel}}} + comments := []wireComment{ + {User: wireUser{"mallory"}, Body: SHAWaivedMarker("forged"), CreatedAt: "2026-11-17T01:00:00Z"}, + {User: wireUser{testHiveAppBotLogin}, Body: SHAWaivedMarker("alice") + "\nwaived", CreatedAt: "2026-11-17T02:00:00Z"}, + } + org, repo := "testorg", "console" + server := httptest.NewServer(buildSHASoftMux(t, org, repo, issue, comments, nil, rec)) + defer server.Close() + c := newTestClient(t, server, org, []string{repo}) + c.SetAppBotLogin(testHiveAppBotLogin) + if _, err := c.EnforceSHAHold(context.Background(), SHAHoldConfig{PrimaryRepo: repo, AIAuthor: "hive-bot"}); err != nil { + t.Fatal(err) + } + if got := c.SHAWaivedBy("testorg/console", 7); got != "alice" { + t.Fatalf("SHAWaivedBy = %q, want alice (a human's forged marker is ignored)", got) + } + // The sweep resolved the waiver once; a second sweep does not list again. + if !c.shaWaiverKnown("testorg/console", 7) { + t.Fatal("waiver not cached after the first sweep") + } + if got := shaWaivedBy("no marker"); got != "" || !strings.Contains(SHAWaivedMarker("bob"), "by=bob") { + t.Fatalf("marker round-trip broken: %q", got) + } +} + +// Once overridden, the held issue reaches the actionable set (and so the +// stage-label pass); without the override it stays filtered. +func TestEnumerateActionable_WaivedSHAHoldIsEligible(t *testing.T) { + org, repo := "testorg", "testrepo" + issues := []wireIssue{ + {Number: 1, Title: "held", User: wireUser{"stranger"}, Labels: []wireLabel{{Name: "kind/bug"}, {Name: "needs-sha"}}, CreatedAt: hoursAgo(3)}, + {Number: 2, Title: "waived", User: wireUser{"stranger"}, Labels: []wireLabel{{Name: "kind/bug"}, {Name: "needs-sha"}, {Name: SHAWaivedLabel}}, CreatedAt: hoursAgo(3)}, + } + server := httptest.NewServer(buildMux(t, org, repo, issues, nil)) + t.Cleanup(server.Close) + c := newTestClient(t, server, org, []string{repo}) + result, err := c.EnumerateActionable(context.Background()) + if err != nil { + t.Fatalf("EnumerateActionable: %v", err) + } + nums := actionableNumbers(result) + if nums[1] { + t.Error("positive control failed: needs-sha without a waiver must stay out of the actionable set") + } + if !nums[2] { + t.Error("a waived issue must be eligible for the actionable set and the stage-label pass") + } +} diff --git a/src/pkg/github/sha_hold_soft_test.go b/src/pkg/github/sha_hold_soft_test.go index bd9b2ce47b..1266a865ec 100644 --- a/src/pkg/github/sha_hold_soft_test.go +++ b/src/pkg/github/sha_hold_soft_test.go @@ -81,12 +81,12 @@ func TestEnforceSHAHold_TrustedReporterGetsSoftLabel(t *testing.T) { want SHAHoldResult }{ { - name: "member without SHA gets needs-sha, not hold", - association: "MEMBER", - labels: []wireLabel{{Name: "kind/bug"}}, - wantAdded: []string{"needs-sha"}, - wantComments: 1, - want: SHAHoldResult{Held: 1}, + // hivecommons/hive#18866: the gate is for outside reporters; a + // maintainer's issue is exempt and never gets the label. + name: "member without SHA is exempt, not held", + association: "MEMBER", + labels: []wireLabel{{Name: "kind/bug"}}, + want: SHAHoldResult{Skipped: 1}, }, { // hivecommons/hive#18468: the hive never applies `hold` @@ -107,7 +107,9 @@ func TestEnforceSHAHold_TrustedReporterGetsSoftLabel(t *testing.T) { want: SHAHoldResult{Unheld: 1}, }, { - name: "sweep's legacy hard hold on a member issue is softened", + // Exempt since #18866, so the sweep's own legacy hold is lifted + // rather than swapped for needs-sha. + name: "sweep's legacy hard hold on a member issue is lifted", association: "OWNER", labels: []wireLabel{{Name: "kind/bug"}, {Name: "hold"}}, comments: []wireComment{{User: wireUser{testHiveAppBotLogin}, Body: shaHoldComment, CreatedAt: "2026-09-15T12:00:01Z"}}, @@ -115,9 +117,8 @@ func TestEnforceSHAHold_TrustedReporterGetsSoftLabel(t *testing.T) { "event": "labeled", "created_at": "2026-09-15T12:00:00Z", "actor": map[string]string{"login": testHiveAppBotLogin}, "label": map[string]string{"name": "hold"}, }}, - wantAdded: []string{"needs-sha"}, wantRemoved: []string{"hold"}, - want: SHAHoldResult{Softened: 1}, + want: SHAHoldResult{Unheld: 1}, }, { name: "human hold on a member issue is left alone", From 29e68c12aa665109ffdae6c6e696c0b4b5950da5 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Wed, 18 Nov 2026 13:38:12 -0500 Subject: [PATCH 2/2] docs: refresh scale-envelope citation after rebase Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- src/docs/scale-envelope.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/scale-envelope.md b/src/docs/scale-envelope.md index dfa38dd9e8..0886ff1184 100644 --- a/src/docs/scale-envelope.md +++ b/src/docs/scale-envelope.md @@ -34,7 +34,7 @@ ones to: 2. **Truncation must preserve the prioritization signal, not cut an arbitrary slice.** This holds today and is easy to assume backwards: - Issues are sorted by actionable rank tier, then **oldest first** within each tier before any cap is applied - (`RankActionableIssues`, `src/pkg/github/client.go:5391-5402`, descending `AgeMinutes` within each tier). + (`RankActionableIssues`, `src/pkg/github/client.go:5440-5450`, descending `AgeMinutes` within each tier). - PRs are sorted by **review class then oldest-first within class** (`SortPullRequestsForReview`, `src/pkg/github/review_priority.go:334`; fixes → refactors/docs → tests).