From 6902ead4e83de5e385e3cf660673370323afdd97 Mon Sep 17 00:00:00 2001 From: Karibhou Date: Sat, 7 Nov 2026 23:08:41 +0000 Subject: [PATCH 1/2] =?UTF-8?q?=E2=9C=A8=20knowledge:=20review=20flow=20an?= =?UTF-8?q?d=20never-prime=20for=20CLI=20auto-memory=20drafts,=20legacy=20?= =?UTF-8?q?drain?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drained CLI-memory facts are agent-written text, so while one is still a draft it never reaches an agent, whatever include_states admits: - FilterByLifecycleFor (kick primer, knowledge advisor) drops it even for a draft-admitting scope or primer config, or an author match. The operator filter FilterByLifecycle still lists it for review. - TOCScope.HideAutoMemoryDrafts, set by AgentScope and on every ?agent= TOC/entry/effective read, drops it as reason "lifecycle". - AutoPromoteCandidates skips pages tagged cli-memory. Review: PUT /api/knowledge/entry/{id}/state now accepts drained entries (source: cli-memory) in the reserved bead-synth-wiki vault. Before this change they could never be approved. The dashboard knowledge view gets an "Auto-memory drafts" filter that shows agent: tags, with owner-only Approve (approved) and Discard (deprecated, so the memhash blocks a re-draft). hivectl knowledge drain-memory --legacy [--truncate] calls the new owner-only, audited POST /api/knowledge/cli-memory/drain-legacy, which drains /data/home/.claude/projects/*/memory into drafts tagged agent:shared. Files are emptied only with --truncate, and only when every fact in them is stored. Docs: Auto-memory drafts section in knowledge-lifecycle.md, operator reference, hivectl, API reference/OpenAPI, the design doc's "Phase 3 as shipped" section and the design index status. Route citations re-anchored with check-docs-citations.py --fix. Hive-Run: hivecommons/hive#17058 Hive-Plan: cli-memory-drain.md#phase-3--review-flow-draft-exclusion-legacy-migration-operator-docs Hive-Spec: cli-memory-drain#phase-3 Signed-off-by: Karibhou --- changelog.d/added-17058-auto-memory-review.md | 1 + dashboard/openapi.json | 95 ++++++++++ src/docs/agent-knowledge-and-memory.md | 16 +- src/docs/api-reference/agents-and-controls.md | 16 +- src/docs/api-reference/beads.md | 10 +- src/docs/api-reference/configuration.md | 6 +- src/docs/api-reference/dashboard-misc.md | 22 +-- src/docs/api-reference/inception.md | 28 +-- src/docs/api-reference/knowledge.md | 77 ++++---- src/docs/api-reference/nous.md | 50 +++--- src/docs/api-reference/packs-and-acmm.md | 2 +- src/docs/design/README.md | 2 +- src/docs/design/cli-memory-drain.md | 31 ++++ src/docs/hivectl.md | 16 ++ src/docs/knowledge-lifecycle.md | 58 +++++- .../operator-reference/runtime-and-quota.md | 18 ++ src/pkg/dashboard/api.go | 1 + src/pkg/dashboard/api_knowledge_cli_memory.go | 94 ++++++++++ .../api_knowledge_cli_memory_test.go | 165 ++++++++++++++++++ src/pkg/dashboard/api_knowledge_toc.go | 13 +- .../knowledge_auto_memory_ui_test.go | 107 ++++++++++++ .../owner_only_handlers_deny_test.go | 1 + src/pkg/dashboard/static-src/js/knowledge.js | 50 ++++++ src/pkg/dashboard/static/index.html | 50 ++++++ src/pkg/hivectl/commands/knowledge.go | 27 +++ .../hivectl/commands/knowledge_more_test.go | 41 +++++ src/pkg/knowledge/api.go | 29 ++- src/pkg/knowledge/auto_memory.go | 36 ++++ src/pkg/knowledge/auto_memory_test.go | 95 ++++++++++ src/pkg/knowledge/climemory/drain.go | 5 +- src/pkg/knowledge/climemory/legacy.go | 97 ++++++++++ src/pkg/knowledge/climemory/legacy_test.go | 113 ++++++++++++ src/pkg/knowledge/lifecycle.go | 24 ++- src/pkg/knowledge/promote.go | 6 +- src/pkg/knowledge/promote_test.go | 2 + src/pkg/knowledge/toc.go | 9 +- .../kick_priming_auto_memory_test.go | 97 ++++++++++ 37 files changed, 1377 insertions(+), 133 deletions(-) create mode 100644 changelog.d/added-17058-auto-memory-review.md create mode 100644 src/pkg/dashboard/api_knowledge_cli_memory.go create mode 100644 src/pkg/dashboard/api_knowledge_cli_memory_test.go create mode 100644 src/pkg/dashboard/knowledge_auto_memory_ui_test.go create mode 100644 src/pkg/knowledge/auto_memory.go create mode 100644 src/pkg/knowledge/auto_memory_test.go create mode 100644 src/pkg/knowledge/climemory/legacy.go create mode 100644 src/pkg/knowledge/climemory/legacy_test.go create mode 100644 src/pkg/scheduler/kick_priming_auto_memory_test.go diff --git a/changelog.d/added-17058-auto-memory-review.md b/changelog.d/added-17058-auto-memory-review.md new file mode 100644 index 0000000000..8114359e4d --- /dev/null +++ b/changelog.d/added-17058-auto-memory-review.md @@ -0,0 +1 @@ +- Drained CLI-memory drafts (`cli-memory` tag) never reach an agent while they are drafts: not through the kick primer or knowledge advisor, not through any `?agent=` TOC or entry read, and not through curator auto-promotion, even when `include_states` admits drafts. The dashboard's knowledge view gains an **Auto-memory drafts** filter that shows each draft's `agent:` tags with owner-only Approve and Discard actions. A new owner-only command, `hivectl knowledge drain-memory --legacy [--truncate]`, drains the shared `/data/home/.claude/projects/*/memory` store into drafts tagged `agent:shared` (#17058). diff --git a/dashboard/openapi.json b/dashboard/openapi.json index 07385e505d..f04385093e 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -15099,6 +15099,101 @@ } } }, + "/api/knowledge/cli-memory/drain-legacy": { + "post": { + "tags": [ + "Knowledge" + ], + "summary": "Drain the shared home's legacy Claude memory into draft knowledge", + "description": "Owner-only, one-shot drain of every `/data/home/.claude/projects/*/memory` store that the per-agent CLI homes (#17039) left behind. Each memory fact becomes a `state: draft` entry in the `bead-synth-wiki` vault tagged `cli-memory` and `agent:shared`, deduplicated by content hash against every entry already in the vault. Drafts are never primed until approved through `PUT /api/knowledge/entry/{id}/state`. The memory files are emptied only when `truncate` is true, and only files whose every fact is now in the vault. The run is written to the audit log.", + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "truncate": { + "type": "boolean", + "description": "Empty each memory file whose facts are all stored (default false)" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Drain result", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "store": { + "type": "string" + }, + "agent": { + "type": "string" + }, + "sources": { + "type": "integer" + }, + "drained": { + "type": "integer" + }, + "dupes": { + "type": "integer" + }, + "skipped": { + "type": "integer", + "description": "Facts over the 200-per-drain cap; run again to drain them" + }, + "truncate": { + "type": "boolean" + }, + "truncated": { + "type": "array", + "items": { + "type": "string" + } + }, + "kept": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Files left in place because a fact in them is not stored yet" + }, + "errors": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + }, + "400": { + "description": "Invalid request body" + }, + "403": { + "description": "Caller is not an owner" + }, + "409": { + "description": "The bead-synth-wiki vault is not connected" + }, + "500": { + "description": "The legacy project tree could not be listed" + }, + "503": { + "description": "Knowledge not enabled" + } + } + } + }, "/api/knowledge/stats": { "get": { "tags": [ diff --git a/src/docs/agent-knowledge-and-memory.md b/src/docs/agent-knowledge-and-memory.md index eddf4494d8..068796f960 100644 --- a/src/docs/agent-knowledge-and-memory.md +++ b/src/docs/agent-knowledge-and-memory.md @@ -235,16 +235,20 @@ Do not treat the following as current behaviour; follow the links. [PR #17039](https://github.com/hivecommons/hive/pull/17039) (per-agent `.claude`/`.gemini`/`.bob`, described above). Hives upgraded from before it still hold the old shared store under `/data/home/.claude/projects`; it is - left in place and logged once, remove or drain it by hand. + left in place and logged once. Drain it with + `hivectl knowledge drain-memory --legacy` (see + [Auto-memory drafts](knowledge-lifecycle.md#auto-memory-drafts)) or remove + it by hand. - [#17032](https://github.com/hivecommons/hive/issues/17032) — done: `agents.cli_memory.auto_memory` (default off) and `agents.cli_memory.clear_on_kick`, described above. - [#17033](https://github.com/hivecommons/hive/issues/17033) — done for the - kick-time drain: `agents.cli_memory.drain_to_knowledge`, described above. - Still open: a Claude Code `SessionEnd` hook that drains without waiting - for the next kick, and a one-shot drain of a pre-#17031 shared store - (sub-issues [#17057](https://github.com/hivecommons/hive/issues/17057), - [#17058](https://github.com/hivecommons/hive/issues/17058)). + kick-time drain (`agents.cli_memory.drain_to_knowledge`, described above), + the review flow, the hard exclusion of drained drafts from every agent read + and the one-shot legacy drain + ([#17058](https://github.com/hivecommons/hive/issues/17058)). Still open: a + Claude Code `SessionEnd` hook that drains without waiting for the next kick + ([#17057](https://github.com/hivecommons/hive/issues/17057)). - Repo `AGENTS.md` injection still requires `project.checkouts_dir`; nearest- file (`ParseNearest`) targeting is deferred ([agents-md.md](agents-md.md)). diff --git a/src/docs/api-reference/agents-and-controls.md b/src/docs/api-reference/agents-and-controls.md index 7292ce1e24..b00c20e76c 100644 --- a/src/docs/api-reference/agents-and-controls.md +++ b/src/docs/api-reference/agents-and-controls.md @@ -23,15 +23,15 @@ 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:174` | | `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 and the top 10 most-reworked PRs | `pkg/dashboard/api.go:175` | | `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:238` | -| `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:507` | -| `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:510` | -| `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:511` | -| `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:515` | +| `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:508` | +| `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:511` | +| `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:512` | +| `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:516` | | `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:16` | -| `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:519` | -| `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:520` | -| `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:522` | -| `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), `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:525` | +| `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:520` | +| `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:521` | +| `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:523` | +| `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), `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:526` | | `GET` | `/api/agents` | Dashboard auth/session | Agents List | `pkg/dashboard/api.go:319` | | `POST` | `/api/agents` | Owner only | Agent Create | `pkg/dashboard/api.go:320` | | `POST` | `/api/agents/import` | Owner only | Agent Import | `pkg/dashboard/api.go:321` | diff --git a/src/docs/api-reference/beads.md b/src/docs/api-reference/beads.md index a10c7338b2..d6c1e76110 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:491` | -| `GET` | `/api/beads/{agent}` | Dashboard auth/session | Beads List | `pkg/dashboard/api.go:492` | -| `POST` | `/api/beads/{agent}` | Owner only | Beads Create | `pkg/dashboard/api.go:493` | -| `POST` | `/api/beads/reset` | Owner only | Beads Reset | `pkg/dashboard/api.go:494` | -| `POST` | `/api/beads/reset/{agent}` | Owner only | Beads Reset Agent | `pkg/dashboard/api.go:495` | +| `GET` | `/api/beads` | Dashboard auth/session | Beads List | `pkg/dashboard/api.go:492` | +| `GET` | `/api/beads/{agent}` | Dashboard auth/session | Beads List | `pkg/dashboard/api.go:493` | +| `POST` | `/api/beads/{agent}` | Owner only | Beads Create | `pkg/dashboard/api.go:494` | +| `POST` | `/api/beads/reset` | Owner only | Beads Reset | `pkg/dashboard/api.go:495` | +| `POST` | `/api/beads/reset/{agent}` | Owner only | Beads Reset Agent | `pkg/dashboard/api.go:496` | diff --git a/src/docs/api-reference/configuration.md b/src/docs/api-reference/configuration.md index 223d90bc72..60b6eb6822 100644 --- a/src/docs/api-reference/configuration.md +++ b/src/docs/api-reference/configuration.md @@ -85,7 +85,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `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:362` | | `GET` | `/api/compliance/attestations` | Owner only | Owner attestations, newest first (`?framework=` filters) ([#11081](https://github.com/hivecommons/hive/issues/11081)) | `pkg/dashboard/api.go:363` | | `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:364` | -| `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:532` | +| `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:533` | | `GET` | `/api/config/governor/threshold-scaling` | Owner only | Governor Threshold Scaling Get | `pkg/dashboard/api.go:219` | | `PUT` | `/api/config/governor/threshold-scaling` | Owner only | Governor Threshold Scaling Set | `pkg/dashboard/api.go:220` | @@ -94,8 +94,8 @@ 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:229` | | `GET` | `/api/config/escalation` | Owner only | Escalation Config Get | `pkg/dashboard/api.go:232` | | `PUT` | `/api/config/escalation` | Owner only | Escalation Config Set | `pkg/dashboard/api.go:233` | -| `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:528` | -| `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:529` | +| `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:529` | +| `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:530` | | `GET` | `/api/config/review` | Dashboard auth/session | Review Config Get | `pkg/dashboard/api.go:236` | | `PUT` | `/api/config/review` | Owner only | Review Config Set | `pkg/dashboard/api.go:239` | | `PUT` | `/api/config/governor/features` | Owner only | Governor Features | `pkg/dashboard/api.go:245` | diff --git a/src/docs/api-reference/dashboard-misc.md b/src/docs/api-reference/dashboard-misc.md index 1d299053a1..52ee30146e 100644 --- a/src/docs/api-reference/dashboard-misc.md +++ b/src/docs/api-reference/dashboard-misc.md @@ -25,7 +25,7 @@ The monitor renders CI and Review concurrently on one shared PR row; see | 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:62` | -| `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:502` | +| `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:503` | | `POST` | `/api/presence` | Dashboard auth/session | Presence | `pkg/dashboard/api.go:65` | | `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:68` | | `GET` | `/api/prompt-history` | Dashboard auth/session | Prompt History | `pkg/dashboard/api.go:66` | @@ -40,18 +40,18 @@ The monitor renders CI and Review concurrently on one shared PR row; see | `GET` | `/api/convergence/soak` | Owner only | Convergence Soak Status | `pkg/dashboard/api.go:263` | -| `POST` | `/api/plan/from-issue` | Dashboard auth/session | Plan From Issue | `pkg/dashboard/api.go:454` | -| `GET` | `/api/plan/{epicID}` | Dashboard auth/session | Plan Tree | `pkg/dashboard/api.go:457` | -| `POST` | `/api/plan/{epicID}/approve` | Owner only | Plan Approve | `pkg/dashboard/api.go:458` | -| `POST` | `/api/plan/{epicID}/reject` | Owner only | Plan Reject | `pkg/dashboard/api.go:460` | -| `POST` | `/api/plan/{epicID}/child/{childID}` | Owner only | Plan Child Action | `pkg/dashboard/api.go:461` | +| `POST` | `/api/plan/from-issue` | Dashboard auth/session | Plan From Issue | `pkg/dashboard/api.go:455` | +| `GET` | `/api/plan/{epicID}` | Dashboard auth/session | Plan Tree | `pkg/dashboard/api.go:458` | +| `POST` | `/api/plan/{epicID}/approve` | Owner only | Plan Approve | `pkg/dashboard/api.go:459` | +| `POST` | `/api/plan/{epicID}/reject` | Owner only | Plan Reject | `pkg/dashboard/api.go:461` | +| `POST` | `/api/plan/{epicID}/child/{childID}` | Owner only | Plan Child Action | `pkg/dashboard/api.go:462` | | `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:305` | | `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:306` | -| `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:539` | +| `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:540` | | `GET` | `/api/widget` | Dashboard auth/session | Widget | `pkg/dashboard/api.go:117` | | `GET` | `/api/pane/{agent}` | Dashboard auth/session | Pane | `pkg/dashboard/api.go:122` | | `GET` | `/api/role` | Dashboard auth/session | Role | `pkg/dashboard/api.go:136` | @@ -63,10 +63,10 @@ The monitor renders CI and Review concurrently on one shared PR row; see | `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:191` | | `POST` | `/api/prs/{owner}/{repo}/{number}/queue-automerge` | Merger/owner role | Queue PRAuto Merge | `pkg/dashboard/api.go:192` | | `GET` | `/api/inference/models/{backend}` | Dashboard auth/session | Inference Models | `pkg/dashboard/api.go:371` | -| `GET` | `/api/hive-id` | Dashboard auth/session | Hive IDGet | `pkg/dashboard/api.go:433` | -| `PUT` | `/api/hive-id` | Owner only | Hive IDSet | `pkg/dashboard/api.go:434` | -| `POST` | `/api/chat` | Dashboard auth/session | Chat | `pkg/dashboard/api.go:463` | -| `GET` | `/api/auth/token` | Public | Auth Token | `pkg/dashboard/api.go:497` | +| `GET` | `/api/hive-id` | Dashboard auth/session | Hive IDGet | `pkg/dashboard/api.go:434` | +| `PUT` | `/api/hive-id` | Owner only | Hive IDSet | `pkg/dashboard/api.go:435` | +| `POST` | `/api/chat` | Dashboard auth/session | Chat | `pkg/dashboard/api.go:464` | +| `GET` | `/api/auth/token` | Public | Auth Token | `pkg/dashboard/api.go:498` | | `GET` | `/api/v1/` | GitHub token | Contributor v1 API dispatcher | `pkg/dashboard/api_contribute.go:350` | | `POST` | `/api/v1/` | GitHub token | Contributor v1 API dispatcher | `pkg/dashboard/api_contribute.go:351` | | `GET` | `/api/docs` | Dashboard auth/session | APIDocs | `pkg/dashboard/api_contribute.go:352` | diff --git a/src/docs/api-reference/inception.md b/src/docs/api-reference/inception.md index a68933af0e..dc1bcdb41b 100644 --- a/src/docs/api-reference/inception.md +++ b/src/docs/api-reference/inception.md @@ -5,17 +5,17 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| -| `POST` | `/api/inception/start` | Owner only | Inception Start | `pkg/dashboard/api.go:436` | -| `POST` | `/api/inception/scan` | Owner only | Inception Scan | `pkg/dashboard/api.go:437` | -| `GET` | `/api/inception/state` | Dashboard auth/session | Inception State | `pkg/dashboard/api.go:438` | -| `POST` | `/api/inception/questions` | Owner only | Inception Set Questions | `pkg/dashboard/api.go:439` | -| `POST` | `/api/inception/answer` | Owner only | Inception Answer | `pkg/dashboard/api.go:440` | -| `POST` | `/api/inception/facts` | Owner only | Inception Record Facts | `pkg/dashboard/api.go:441` | -| `GET` | `/api/inception/scaffold` | Dashboard auth/session | Inception Scaffold | `pkg/dashboard/api.go:442` | -| `POST` | `/api/inception/approve` | Owner only | Inception Approve | `pkg/dashboard/api.go:443` | -| `POST` | `/api/inception/reset` | Owner only | Inception Reset | `pkg/dashboard/api.go:444` | -| `GET` | `/api/inception/ideation-facts` | Dashboard auth/session | Inception Ideation Facts | `pkg/dashboard/api.go:445` | -| `GET` | `/api/inception/download` | Dashboard auth/session | Inception Download | `pkg/dashboard/api.go:446` | -| `GET` | `/api/inception/has-files` | Dashboard auth/session | Inception Has Files | `pkg/dashboard/api.go:447` | -| `PUT` | `/api/inception/wiki-name` | Owner only | Inception Rename Wiki | `pkg/dashboard/api.go:448` | -| `POST` | `/api/inception/import` | Owner only | Inception Import | `pkg/dashboard/api.go:449` | +| `POST` | `/api/inception/start` | Owner only | Inception Start | `pkg/dashboard/api.go:437` | +| `POST` | `/api/inception/scan` | Owner only | Inception Scan | `pkg/dashboard/api.go:438` | +| `GET` | `/api/inception/state` | Dashboard auth/session | Inception State | `pkg/dashboard/api.go:439` | +| `POST` | `/api/inception/questions` | Owner only | Inception Set Questions | `pkg/dashboard/api.go:440` | +| `POST` | `/api/inception/answer` | Owner only | Inception Answer | `pkg/dashboard/api.go:441` | +| `POST` | `/api/inception/facts` | Owner only | Inception Record Facts | `pkg/dashboard/api.go:442` | +| `GET` | `/api/inception/scaffold` | Dashboard auth/session | Inception Scaffold | `pkg/dashboard/api.go:443` | +| `POST` | `/api/inception/approve` | Owner only | Inception Approve | `pkg/dashboard/api.go:444` | +| `POST` | `/api/inception/reset` | Owner only | Inception Reset | `pkg/dashboard/api.go:445` | +| `GET` | `/api/inception/ideation-facts` | Dashboard auth/session | Inception Ideation Facts | `pkg/dashboard/api.go:446` | +| `GET` | `/api/inception/download` | Dashboard auth/session | Inception Download | `pkg/dashboard/api.go:447` | +| `GET` | `/api/inception/has-files` | Dashboard auth/session | Inception Has Files | `pkg/dashboard/api.go:448` | +| `PUT` | `/api/inception/wiki-name` | Owner only | Inception Rename Wiki | `pkg/dashboard/api.go:449` | +| `POST` | `/api/inception/import` | Owner only | Inception Import | `pkg/dashboard/api.go:450` | diff --git a/src/docs/api-reference/knowledge.md b/src/docs/api-reference/knowledge.md index 2c508db464..8dfc69b6e6 100644 --- a/src/docs/api-reference/knowledge.md +++ b/src/docs/api-reference/knowledge.md @@ -7,35 +7,36 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f |---|---|---|---|---| | `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:373` | | `GET` | `/api/knowledge/export` | Dashboard auth/session | Knowledge Export | `pkg/dashboard/api.go:374` | -| `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:382` | +| `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:383` | | `GET` | `/api/knowledge/search` | Dashboard auth/session | Knowledge Search | `pkg/dashboard/api.go:375` | | `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:376` | | `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:377` | | `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:378` | -| `GET` | `/api/knowledge/public` | Dashboard auth/session | Public Knowledge MCP sharing status (`enabled`, `tags`, `source`, endpoint URL) | `pkg/dashboard/api.go:383` | -| `PUT` | `/api/knowledge/public` | Owner only | Persist public Knowledge MCP sharing setting; overrides env vars until changed | `pkg/dashboard/api.go:384` | -| `GET` | `/api/knowledge/health` | Dashboard auth/session | Knowledge Health | `pkg/dashboard/api.go:385` | -| `GET` | `/api/knowledge/stats` | Dashboard auth/session | Knowledge Stats | `pkg/dashboard/api.go:386` | -| `GET` | `/api/knowledge/graph` | Dashboard auth/session | Knowledge Graph | `pkg/dashboard/api.go:387` | -| `GET` | `/api/knowledge/fact-history` | Dashboard auth/session | Fact History | `pkg/dashboard/api.go:388` | -| `POST` | `/api/knowledge/create` | Dashboard auth/session | Knowledge Create | `pkg/dashboard/api.go:389` | -| `POST` | `/api/knowledge/import` | Dashboard auth/session | Knowledge Import | `pkg/dashboard/api.go:390` | -| `POST` | `/api/knowledge/promote` | Dashboard auth/session | Knowledge Promote | `pkg/dashboard/api.go:396` | -| `GET` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs List | `pkg/dashboard/api.go:397` | -| `POST` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs Add | `pkg/dashboard/api.go:398` | -| `DELETE` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs Remove | `pkg/dashboard/api.go:399` | -| `PUT` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Update | `pkg/dashboard/api.go:400` | -| `DELETE` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Delete | `pkg/dashboard/api.go:401` | -| `GET` | `/api/knowledge/{layer}` | Dashboard auth/session | Knowledge Layer | `pkg/dashboard/api.go:402` | -| `GET` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Fact | `pkg/dashboard/api.go:403` | -| `PUT` | `/api/knowledge/enabled` | Owner only | Knowledge Toggle | `pkg/dashboard/api.go:404` | -| `GET` | `/api/knowledge/bead-synthesizer` | Dashboard auth/session | Bead Synth Status | `pkg/dashboard/api.go:405` | -| `PUT` | `/api/knowledge/bead-synthesizer/enabled` | Owner only | Bead Synth Toggle | `pkg/dashboard/api.go:406` | -| `GET` | `/api/knowledge/vaults` | Dashboard auth/session | Vaults List | `pkg/dashboard/api.go:407` | -| `POST` | `/api/knowledge/vaults` | Owner only | Vaults Connect | `pkg/dashboard/api.go:408` | -| `DELETE` | `/api/knowledge/vaults` | Dashboard auth/session | Vaults Disconnect | `pkg/dashboard/api.go:409` | -| `POST` | `/api/knowledge/vaults/reindex` | Dashboard auth/session | Vaults Reindex | `pkg/dashboard/api.go:410` | -| `GET` | `/api/knowledge/vaults/{name}/facts` | Dashboard auth/session | Vault Facts | `pkg/dashboard/api.go:411` | +| `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:380` | +| `GET` | `/api/knowledge/public` | Dashboard auth/session | Public Knowledge MCP sharing status (`enabled`, `tags`, `source`, endpoint URL) | `pkg/dashboard/api.go:384` | +| `PUT` | `/api/knowledge/public` | Owner only | Persist public Knowledge MCP sharing setting; overrides env vars until changed | `pkg/dashboard/api.go:385` | +| `GET` | `/api/knowledge/health` | Dashboard auth/session | Knowledge Health | `pkg/dashboard/api.go:386` | +| `GET` | `/api/knowledge/stats` | Dashboard auth/session | Knowledge Stats | `pkg/dashboard/api.go:387` | +| `GET` | `/api/knowledge/graph` | Dashboard auth/session | Knowledge Graph | `pkg/dashboard/api.go:388` | +| `GET` | `/api/knowledge/fact-history` | Dashboard auth/session | Fact History | `pkg/dashboard/api.go:389` | +| `POST` | `/api/knowledge/create` | Dashboard auth/session | Knowledge Create | `pkg/dashboard/api.go:390` | +| `POST` | `/api/knowledge/import` | Dashboard auth/session | Knowledge Import | `pkg/dashboard/api.go:391` | +| `POST` | `/api/knowledge/promote` | Dashboard auth/session | Knowledge Promote | `pkg/dashboard/api.go:397` | +| `GET` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs List | `pkg/dashboard/api.go:398` | +| `POST` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs Add | `pkg/dashboard/api.go:399` | +| `DELETE` | `/api/knowledge/subscriptions` | Dashboard auth/session | Knowledge Subs Remove | `pkg/dashboard/api.go:400` | +| `PUT` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Update | `pkg/dashboard/api.go:401` | +| `DELETE` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Delete | `pkg/dashboard/api.go:402` | +| `GET` | `/api/knowledge/{layer}` | Dashboard auth/session | Knowledge Layer | `pkg/dashboard/api.go:403` | +| `GET` | `/api/knowledge/{layer}/{slug}` | Dashboard auth/session | Knowledge Fact | `pkg/dashboard/api.go:404` | +| `PUT` | `/api/knowledge/enabled` | Owner only | Knowledge Toggle | `pkg/dashboard/api.go:405` | +| `GET` | `/api/knowledge/bead-synthesizer` | Dashboard auth/session | Bead Synth Status | `pkg/dashboard/api.go:406` | +| `PUT` | `/api/knowledge/bead-synthesizer/enabled` | Owner only | Bead Synth Toggle | `pkg/dashboard/api.go:407` | +| `GET` | `/api/knowledge/vaults` | Dashboard auth/session | Vaults List | `pkg/dashboard/api.go:408` | +| `POST` | `/api/knowledge/vaults` | Owner only | Vaults Connect | `pkg/dashboard/api.go:409` | +| `DELETE` | `/api/knowledge/vaults` | Dashboard auth/session | Vaults Disconnect | `pkg/dashboard/api.go:410` | +| `POST` | `/api/knowledge/vaults/reindex` | Dashboard auth/session | Vaults Reindex | `pkg/dashboard/api.go:411` | +| `GET` | `/api/knowledge/vaults/{name}/facts` | Dashboard auth/session | Vault Facts | `pkg/dashboard/api.go:412` | | `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, plus the `publish` mirror status | `pkg/dashboard/api.go` | @@ -45,19 +46,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:421` | -| `POST` | `/api/knowledge/git-sources` | Owner only | Git Sources Connect | `pkg/dashboard/api.go:422` | -| `DELETE` | `/api/knowledge/git-sources` | Owner only | Git Sources Disconnect | `pkg/dashboard/api.go:423` | -| `POST` | `/api/knowledge/obsidian/sync` | Dashboard auth/session | Obsidian Sync | `pkg/dashboard/api.go:424` | -| `GET` | `/api/knowledge/documents` | Dashboard auth/session | Documents List | `pkg/dashboard/api.go:425` | -| `POST` | `/api/knowledge/documents` | Dashboard auth/session | Documents Import | `pkg/dashboard/api.go:426` | -| `GET` | `/api/knowledge/documents/{slug}` | Dashboard auth/session | Document Get | `pkg/dashboard/api.go:427` | -| `DELETE` | `/api/knowledge/documents/{slug}` | Dashboard auth/session | Document Delete | `pkg/dashboard/api.go:428` | -| `POST` | `/api/knowledge/documents/{slug}/reimport` | Dashboard auth/session | Document Reimport | `pkg/dashboard/api.go:429` | -| `GET` | `/api/knowledge/context7/search` | Dashboard auth/session | Context7 Search | `pkg/dashboard/api.go:430` | -| `POST` | `/api/knowledge/cleanup-orphans` | Dashboard auth/session | Cleanup Orphans | `pkg/dashboard/api.go:431` | -| `GET` | `/api/knowledge/channels` | Dashboard auth/session | Knowledge Channels List | `pkg/dashboard/api.go:394` | -| `POST` | `/api/knowledge/channels` | Dashboard auth/session | Knowledge Channel Create | `pkg/dashboard/api.go:395` | +| `GET` | `/api/knowledge/git-sources` | Dashboard auth/session | Git Sources List | `pkg/dashboard/api.go:422` | +| `POST` | `/api/knowledge/git-sources` | Owner only | Git Sources Connect | `pkg/dashboard/api.go:423` | +| `DELETE` | `/api/knowledge/git-sources` | Owner only | Git Sources Disconnect | `pkg/dashboard/api.go:424` | +| `POST` | `/api/knowledge/obsidian/sync` | Dashboard auth/session | Obsidian Sync | `pkg/dashboard/api.go:425` | +| `GET` | `/api/knowledge/documents` | Dashboard auth/session | Documents List | `pkg/dashboard/api.go:426` | +| `POST` | `/api/knowledge/documents` | Dashboard auth/session | Documents Import | `pkg/dashboard/api.go:427` | +| `GET` | `/api/knowledge/documents/{slug}` | Dashboard auth/session | Document Get | `pkg/dashboard/api.go:428` | +| `DELETE` | `/api/knowledge/documents/{slug}` | Dashboard auth/session | Document Delete | `pkg/dashboard/api.go:429` | +| `POST` | `/api/knowledge/documents/{slug}/reimport` | Dashboard auth/session | Document Reimport | `pkg/dashboard/api.go:430` | +| `GET` | `/api/knowledge/context7/search` | Dashboard auth/session | Context7 Search | `pkg/dashboard/api.go:431` | +| `POST` | `/api/knowledge/cleanup-orphans` | Dashboard auth/session | Cleanup Orphans | `pkg/dashboard/api.go:432` | +| `GET` | `/api/knowledge/channels` | Dashboard auth/session | Knowledge Channels List | `pkg/dashboard/api.go:395` | +| `POST` | `/api/knowledge/channels` | Dashboard auth/session | Knowledge Channel Create | `pkg/dashboard/api.go:396` | | `GET` | `/api/knowledge/connectors` | Dashboard auth/session | Knowledge connector statuses and publish mirror status (`{"connectors": [...], "publish": {...}\|null}`, see [knowledge-connectors.md](../knowledge-connectors.md)) | `pkg/dashboard/api_knowledge_connectors.go:23` | | `POST` | `/api/knowledge/connectors/{name}/sync` | Owner only | Start one connector sync now (202; 404 unknown, 409 running) | `pkg/dashboard/api_knowledge_connectors.go:24` | | `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:25` | diff --git a/src/docs/api-reference/nous.md b/src/docs/api-reference/nous.md index 3442e50397..0c61798967 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:465` | -| `GET` | `/api/nous/ledger` | Dashboard auth/session | Nous Ledger | `pkg/dashboard/api.go:466` | -| `GET` | `/api/nous/principles` | Dashboard auth/session | Nous Principles | `pkg/dashboard/api.go:467` | -| `POST` | `/api/nous/approve` | Owner only | Nous Approve | `pkg/dashboard/api.go:468` | -| `POST` | `/api/nous/abort` | Owner only | Nous Abort | `pkg/dashboard/api.go:469` | -| `PUT` | `/api/nous/mode` | Owner only | Nous Mode | `pkg/dashboard/api.go:470` | -| `PUT` | `/api/nous/scope` | Owner only | Nous Scope | `pkg/dashboard/api.go:471` | -| `GET` | `/api/nous/phase` | Dashboard auth/session | Nous Phase | `pkg/dashboard/api.go:472` | -| `PUT` | `/api/nous/gate-decision` | Owner only | Nous Gate Decision | `pkg/dashboard/api.go:473` | -| `GET` | `/api/nous/gate-pending` | Dashboard auth/session | Nous Gate Pending | `pkg/dashboard/api.go:474` | -| `POST` | `/api/nous/gate-respond` | Owner only | Nous Gate Respond | `pkg/dashboard/api.go:475` | -| `GET` | `/api/nous/gate-response` | Dashboard auth/session | Nous Gate Response | `pkg/dashboard/api.go:476` | -| `GET` | `/api/nous/config` | Dashboard auth/session | Nous Config Get | `pkg/dashboard/api.go:477` | -| `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:478` | -| `PUT` | `/api/nous/config/repos` | Owner only | Nous Config Repos — the allow-list of repos experiments may target (empty = any) | `pkg/dashboard/api.go:479` | -| `PUT` | `/api/nous/config/output` | Owner only | Nous Config Output | `pkg/dashboard/api.go:480` | -| `PUT` | `/api/nous/config/fast-fail` | Owner only | Nous Config Fast Fail | `pkg/dashboard/api.go:481` | -| `PUT` | `/api/nous/config/schedule` | Owner only | Nous Config Schedule | `pkg/dashboard/api.go:482` | -| `PUT` | `/api/nous/config/controllables` | Owner only | Nous Config Controllables | `pkg/dashboard/api.go:483` | -| `PUT` | `/api/nous/config/principles` | Owner only | Nous Config Principles | `pkg/dashboard/api.go:484` | -| `DELETE` | `/api/nous/principles/{id}` | Owner only | Nous Delete Principle | `pkg/dashboard/api.go:485` | -| `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:486` | -| `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:487` | -| `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:488` | -| `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:489` | +| `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:466` | +| `GET` | `/api/nous/ledger` | Dashboard auth/session | Nous Ledger | `pkg/dashboard/api.go:467` | +| `GET` | `/api/nous/principles` | Dashboard auth/session | Nous Principles | `pkg/dashboard/api.go:468` | +| `POST` | `/api/nous/approve` | Owner only | Nous Approve | `pkg/dashboard/api.go:469` | +| `POST` | `/api/nous/abort` | Owner only | Nous Abort | `pkg/dashboard/api.go:470` | +| `PUT` | `/api/nous/mode` | Owner only | Nous Mode | `pkg/dashboard/api.go:471` | +| `PUT` | `/api/nous/scope` | Owner only | Nous Scope | `pkg/dashboard/api.go:472` | +| `GET` | `/api/nous/phase` | Dashboard auth/session | Nous Phase | `pkg/dashboard/api.go:473` | +| `PUT` | `/api/nous/gate-decision` | Owner only | Nous Gate Decision | `pkg/dashboard/api.go:474` | +| `GET` | `/api/nous/gate-pending` | Dashboard auth/session | Nous Gate Pending | `pkg/dashboard/api.go:475` | +| `POST` | `/api/nous/gate-respond` | Owner only | Nous Gate Respond | `pkg/dashboard/api.go:476` | +| `GET` | `/api/nous/gate-response` | Dashboard auth/session | Nous Gate Response | `pkg/dashboard/api.go:477` | +| `GET` | `/api/nous/config` | Dashboard auth/session | Nous Config Get | `pkg/dashboard/api.go:478` | +| `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:479` | +| `PUT` | `/api/nous/config/repos` | Owner only | Nous Config Repos — the allow-list of repos experiments may target (empty = any) | `pkg/dashboard/api.go:480` | +| `PUT` | `/api/nous/config/output` | Owner only | Nous Config Output | `pkg/dashboard/api.go:481` | +| `PUT` | `/api/nous/config/fast-fail` | Owner only | Nous Config Fast Fail | `pkg/dashboard/api.go:482` | +| `PUT` | `/api/nous/config/schedule` | Owner only | Nous Config Schedule | `pkg/dashboard/api.go:483` | +| `PUT` | `/api/nous/config/controllables` | Owner only | Nous Config Controllables | `pkg/dashboard/api.go:484` | +| `PUT` | `/api/nous/config/principles` | Owner only | Nous Config Principles | `pkg/dashboard/api.go:485` | +| `DELETE` | `/api/nous/principles/{id}` | Owner only | Nous Delete Principle | `pkg/dashboard/api.go:486` | +| `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:487` | +| `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:488` | +| `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:489` | +| `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:490` | diff --git a/src/docs/api-reference/packs-and-acmm.md b/src/docs/api-reference/packs-and-acmm.md index 58c709831b..29b94afd4e 100644 --- a/src/docs/api-reference/packs-and-acmm.md +++ b/src/docs/api-reference/packs-and-acmm.md @@ -22,7 +22,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `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:349`, `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:350` | | `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:351` | -| `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:546`, `pkg/dashboard/api_repo_item_accept_triage.go` | +| `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:547`, `pkg/dashboard/api_repo_item_accept_triage.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:353`, `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:354` | | `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:355` | diff --git a/src/docs/design/README.md b/src/docs/design/README.md index c9e2e1f213..94c1848d7a 100644 --- a/src/docs/design/README.md +++ b/src/docs/design/README.md @@ -22,7 +22,7 @@ that status is the thing to check before treating a page as current behaviour: - [Crux: the agent runtime boundary](crux.md) — **Stage 1 shipped (v5); Stage 2 blocked on `pkg/config`.** RFC [#13536](https://github.com/hivecommons/hive/issues/13536): names the agent runtime inside Hive (`pkg/agent` and its ring) as Crux, lists what stays in Hive, records the staged plan (in-repo boundary → nested module → `crux serve`) and the naming decision. Inbound and outbound ratchets in `src/internal/testutil/crux_*_ratchet_test.go`, the tmux funnel, `crux.Runtime`, Crux-owned value types, CI path filters and the `crux` CLI are live; the nested module waits on an agent-runtime config leaf (the doc lists the measured outbound edges and prerequisites). -- [Draining CLI auto-memory into draft knowledge](cli-memory-drain.md) — **Design only.** #17033: turns each coding CLI's hidden memory store (Claude Code `projects/*/memory`, Codex `memories`, Gemini `GEMINI.md`) into `draft` knowledge facts tagged `auto-memory` and `agent:`. Claude Code drains through a `SessionEnd` hook; the others drain on the manager side at kick time, before `clear_on_kick`. Decides content-hash dedup across agents, an ingest-only drain with the existing curator as the only promoter, and untrusted-content handling (never primed while draft). Implementation is split into three child issues. +- [Draining CLI auto-memory into draft knowledge](cli-memory-drain.md) — **Partly shipped** (phase 1: manager-side drain; phase 3: review flow, draft exclusion, legacy drain; phase 2, the Claude Code `SessionEnd` hook, is open). #17033: turns each coding CLI's hidden memory store (Claude Code `projects/*/memory`, Codex `memories`, Gemini `GEMINI.md`) into `draft` knowledge facts tagged `cli-memory` and `agent:`. Claude Code drains through a `SessionEnd` hook; the others drain on the manager side at kick time, before `clear_on_kick`. Decides content-hash dedup across agents, an ingest-only drain with the existing curator as the only promoter, and untrusted-content handling (never primed while draft). Implementation is split into three child issues. - [Crux: generic tool policy for the MITM proxy](crux-tool-policy.md) — **Design only (proposed).** #14228, child of #14138: a shared operation vocabulary with per-forge adapters, a `relay()` verdict, deny-by-default for unrecognised operations, and the proxy's evaluation pipeline written down once. It also covers migrating behind a parity test and treating #14211 as the first non-GitHub adapter. diff --git a/src/docs/design/cli-memory-drain.md b/src/docs/design/cli-memory-drain.md index fc6e94af44..5c3899d78c 100644 --- a/src/docs/design/cli-memory-drain.md +++ b/src/docs/design/cli-memory-drain.md @@ -372,6 +372,37 @@ Child: #17058. [Knowledge lifecycle states](../knowledge-lifecycle.md), and the status line in [the design index](README.md) moved to partly shipped or shipped. +#### Phase 3 as shipped + +Where the shipped code differs from the plan above, the shipped code is +authoritative. User-facing behaviour is documented in +[Auto-memory drafts](../knowledge-lifecycle.md#auto-memory-drafts). + +- **Marker.** The drain shipped with the tag `cli-memory` and + `source: cli-memory` frontmatter, not `auto-memory`. + `knowledge.IsAutoMemory` accepts either marker. A fact is excluded when + its effective state is `draft`. +- **Exclusion.** `FilterByLifecycleFor` (the kick primer and the knowledge + advisor) never admits an auto-memory draft. `TOCScope.HideAutoMemoryDrafts` + drops it from every scope `AgentScope` builds and from every `?agent=` TOC, + entry and effective read. The operator filter `FilterByLifecycle` and + operator TOC reads still list it. The public MCP was already approved-only. +- **Review in the reserved vault.** Drained entries live in `bead-synth-wiki`, + which `PUT /api/knowledge/entry/{id}/state` used to refuse outright. It now + accepts entries whose frontmatter says `source: cli-memory`, because the + drain never rewrites an existing entry. The dashboard's **Discard** sets + `deprecated` rather than deleting, so the `memhash` keeps the fact from + being re-drafted. +- **Auto-promotion.** `AutoPromoteCandidates` skips any page tagged + `cli-memory`, whatever its status. +- **Legacy drain.** `hivectl knowledge drain-memory --legacy [--truncate]` + calls the owner-only `POST /api/knowledge/cli-memory/drain-legacy`, which runs + the phase-1 drainer in the hive process. With `--truncate` it empties only + the files whose every fact's `memhash` is now in the vault. +- **Config key.** The operator reference documents the shipped key, + `agents.cli_memory.drain_to_knowledge`. There is no separate + `agents.cli_memory.drain`. + ## References - #17033 — this design's issue. diff --git a/src/docs/hivectl.md b/src/docs/hivectl.md index 3a60efa7f5..2c8a1e3097 100644 --- a/src/docs/hivectl.md +++ b/src/docs/hivectl.md @@ -212,6 +212,22 @@ hivectl knowledge state old-relay deprecated --reason "relay removed" hivectl knowledge state old-relay superseded --superseded-by relay-v2 --reason "relay rewritten" ``` +`drain-memory --legacy` is a one-shot, owner-only drain of the shared +home's Claude auto-memory (`/data/home/.claude/projects/*/memory`), which +per-agent CLI homes stopped writing to but left in place. Each memory fact +becomes a `state: draft` entry in the `bead-synth-wiki` vault tagged +`cli-memory` and `agent:shared`, deduplicated by content hash, via +`POST /api/knowledge/cli-memory/drain-legacy`; the run is audited. Memory files +are left alone unless `--truncate` is given, and even then only files whose +every fact is now stored are emptied (`kept` lists the rest). Review the drafts +as described in +[Auto-memory drafts](knowledge-lifecycle.md#auto-memory-drafts). + +```bash +hivectl knowledge drain-memory --legacy +hivectl knowledge drain-memory --legacy --truncate --output json +``` + `suggest` lets an agent propose a knowledge change without changing what other agents see. It runs locally against a repository checkout (no dashboard call): it writes the change under `.hive/wiki/` (`--dir`, `--repo-root`) and prints diff --git a/src/docs/knowledge-lifecycle.md b/src/docs/knowledge-lifecycle.md index c3f978211f..20dccec447 100644 --- a/src/docs/knowledge-lifecycle.md +++ b/src/docs/knowledge-lifecycle.md @@ -80,7 +80,9 @@ hivectl knowledge state old-deploy-flow deprecated --reason "deploy flow removed with `superseded`. The replacement must be in the same local channel as the entry. Invalid input returns 400. - The entry must be in a local channel (vault). Entries from remote wiki - layers, git sources and the reserved automation channel return 404. + layers, git sources and the reserved automation channel return 404. The one + exception is a drained CLI-memory entry (`source: cli-memory`) in the + `bead-synth-wiki` channel; see [Auto-memory drafts](#auto-memory-drafts). - Every change writes an audit entry: `knowledge_set_state`, or `knowledge_supersede` for supersession. The entry records the actor, the entry id and channel, the previous and new state, `superseded_by`, and the @@ -90,3 +92,57 @@ hivectl knowledge state old-deploy-flow deprecated --reason "deploy flow removed Restoring a fact to `approved` clears its `superseded_by` link. It then reaches primers and the table of contents again. + +## Auto-memory drafts + +With `agents.cli_memory.drain_to_knowledge` on, each agent's coding-CLI memory +(Claude Code `MEMORY.md` and topic files, Codex `memories*/`, Gemini +`GEMINI.md`) is drained into `state: draft` entries in the `bead-synth-wiki` +vault ([#17033](https://github.com/hivecommons/hive/issues/17033)). Each entry +has `source: cli-memory` and the tags `cli-memory`, `agent:`, +`cli:`, `memhash:` and, when the project path names one of the +agent's repos, `repo:/`. The shared home's pre-isolation store is +drained once, on demand, with +[`hivectl knowledge drain-memory --legacy`](hivectl.md); those entries are +tagged `agent:shared`. + +The text is agent-written and unreviewed: a model may have copied it from an +issue body or a fetched page. So an auto-memory draft never reaches an agent +([#17058](https://github.com/hivecommons/hive/issues/17058)): + +- The kick primer and the knowledge advisor never prime it, even when the + primer's `include_states` or the agent's `knowledge.agent_scopes` entry + admits `draft`, and even when its author matches the kicked agent. +- An agent-identified read (`?agent=` on `GET /api/knowledge/toc`, + `GET /api/knowledge/entry/{id}` and `GET /api/knowledge/effective`) never + returns it, whatever `include_states` the request names. The effective view + lists it as excluded with reason `lifecycle`. +- The public knowledge MCP publishes approved facts only. +- The curator's scheduled auto-promotion never selects a page tagged + `cli-memory`; it moves to a broader layer only through a manual promote. + +Operator reads still show these drafts so they can be reviewed: pass +`include_states=draft` to `GET /api/knowledge/search` or +`GET /api/knowledge/toc` without `?agent=`. + +### Reviewing them + +In the dashboard's knowledge view, **🧠 Auto-memory drafts** in the sources +list shows every drained draft with the agents it was drained from. An owner +gets two actions per row, both backed by `PUT /api/knowledge/entry/{id}/state` +and audited: + +- **Approve** sets `approved`. From the next kick on, the entry is primed for + every agent whose scope includes it. +- **Discard** sets `deprecated`. It reaches no agent, and because the drain + deduplicates by `memhash` across all states, the same memory is never drafted + again. Deleting the file instead would let the next drain re-create it. + +Outside the dashboard, list them with +`GET /api/knowledge/search?tag=cli-memory&include_states=draft` and change +their state from the CLI: + +```bash +hivectl knowledge state cli-memory-1a2b3c4d5e6f7a8b approved --reason "verified" +hivectl knowledge state cli-memory-1a2b3c4d5e6f7a8b deprecated --reason "one-off" +``` diff --git a/src/docs/operator-reference/runtime-and-quota.md b/src/docs/operator-reference/runtime-and-quota.md index 06dd942a1d..155b668c2d 100644 --- a/src/docs/operator-reference/runtime-and-quota.md +++ b/src/docs/operator-reference/runtime-and-quota.md @@ -115,6 +115,24 @@ knowledge view or the vault directory and approve them through the normal lifecycle (`PUT /api/knowledge/entry/{id}/state`); nothing promotes them automatically. +A drained draft reaches no agent while it is a draft, even for an agent whose +`knowledge.agent_scopes` entry (or the primer's `include_states`) admits +drafts: the kick primer, the knowledge advisor and every `?agent=` TOC, entry +and effective read skip it, and the curator's auto-promotion never selects +it. Review it under **🧠 Auto-memory drafts** in the dashboard's knowledge +view, where an owner can **Approve** (primed from the next kick) or +**Discard** (deprecated, never re-drafted); see +[Auto-memory drafts](../knowledge-lifecycle.md#auto-memory-drafts). + +The shared `/data/home/.claude/projects/*/memory` store that predates +per-agent CLI homes is not drained at kick time. Drain it once with +`hivectl knowledge drain-memory --legacy` (owner-only, audited as +`knowledge_drain_legacy_memory`): its facts become drafts tagged +`agent:shared`, and the files stay as they are unless `--truncate` is given, +which empties only files whose every fact is now in the vault. The +`bead-synth-wiki` vault must be connected (bead stores configured or +`drain_to_knowledge` on); otherwise the call returns 409. + ## GitHub API quota Agents reach `api.github.com` through the Hive GitHub proxy, which injects the diff --git a/src/pkg/dashboard/api.go b/src/pkg/dashboard/api.go index 7592e45dba..14e30b5401 100644 --- a/src/pkg/dashboard/api.go +++ b/src/pkg/dashboard/api.go @@ -377,6 +377,7 @@ func (s *Server) RegisterAPI(deps *Dependencies) { s.mux.HandleFunc("GET /api/knowledge/effective", s.handleKnowledgeEffective) s.mux.HandleFunc("GET /api/knowledge/entry/{id}", s.handleKnowledgeEntry) s.mux.HandleFunc("PUT /api/knowledge/entry/{id}/state", s.handleKnowledgeEntryState) + s.mux.HandleFunc("POST /api/knowledge/cli-memory/drain-legacy", s.handleKnowledgeDrainLegacyMemory) // Anonymous, owner-switched, read-only MCP surface (#10615). POST only — // the mux answers other verbs with 405, and there is no SSE stream. s.mux.HandleFunc("POST /mcp/knowledge", s.handlePublicKnowledgeMCP) // path == publicKnowledgeMCPPath diff --git a/src/pkg/dashboard/api_knowledge_cli_memory.go b/src/pkg/dashboard/api_knowledge_cli_memory.go new file mode 100644 index 0000000000..e802895c55 --- /dev/null +++ b/src/pkg/dashboard/api_knowledge_cli_memory.go @@ -0,0 +1,94 @@ +package dashboard + +import ( + "errors" + "io" + "net/http" + "strconv" + + "github.com/hivecommons/hive/pkg/knowledge" + "github.com/hivecommons/hive/pkg/knowledge/climemory" +) + +// legacyClaudeProjectsDir is the shared home's Claude project tree that +// #17039 stopped writing to but left in place. A var so tests can point it at +// a temp dir. +var legacyClaudeProjectsDir = "/data/home/.claude/projects" + +// handleKnowledgeDrainLegacyMemory serves POST +// /api/knowledge/cli-memory/drain-legacy (#17058): a one-shot, owner-only, +// audited drain of every /*/memory store into draft +// entries in the bead-synth vault, tagged agent:shared. The memory files are +// emptied only with {"truncate": true}, and only those whose every fact is +// now recorded in the vault. +func (s *Server) handleKnowledgeDrainLegacyMemory(w http.ResponseWriter, r *http.Request) { + if !requireOwnerRole(w, r) { + return + } + var req struct { + Truncate bool `json:"truncate"` + } + if err := decodeBody(r, &req); err != nil && !errors.Is(err, io.EOF) { + jsonError(w, "invalid request body", http.StatusBadRequest) + return + } + if !s.ensureKnowledge() { + jsonError(w, "knowledge not enabled", http.StatusServiceUnavailable) + return + } + vault := s.deps.Knowledge.AutoMemoryVault() + if vault == nil { + jsonError(w, "the bead-synth-wiki vault is not connected; configure bead stores or set agents.cli_memory.drain_to_knowledge so drained drafts land in a vault the primer reads", http.StatusConflict) + return + } + sources, err := climemory.LegacyClaudeSources(legacyClaudeProjectsDir) + if err != nil { + jsonError(w, err.Error(), http.StatusInternalServerError) + return + } + layer := knowledge.LayerPersonal + var repos []string + if cfg := s.deps.Config; cfg != nil { + if l := cfg.Knowledge.BeadSynthesizer.TargetLayer; l != "" { + layer = knowledge.LayerType(l) + } + repos = cfg.Project.Repos + } + drainer := &climemory.Drainer{Dir: vault.RootDir(), Store: vault, Layer: layer} + res := drainer.Drain(climemory.Request{Agent: climemory.LegacyAgent, Repos: repos, Sources: sources}) + errs := append([]error(nil), res.Errors...) + truncated, kept := []string{}, []string{} + if req.Truncate { + t, k, terr := drainer.TruncateDrained(sources) + truncated, kept = append(truncated, t...), append(kept, k...) + if terr != nil { + errs = append(errs, terr) + } + } + errText := make([]string, 0, len(errs)) + for _, e := range errs { + errText = append(errText, e.Error()) + } + + s.auditFromRequest(r, "knowledge_drain_legacy_memory", auditDetail( + "sources", strconv.Itoa(len(sources)), + "drained", strconv.Itoa(res.Drained), + "dupes", strconv.Itoa(res.Dupes), + "skipped", strconv.Itoa(res.Skipped), + "truncate", strconv.FormatBool(req.Truncate), + "truncated", strconv.Itoa(len(truncated)), + "errors", strconv.Itoa(len(errText)), + ), "") + jsonResponse(w, map[string]interface{}{ + "store": vault.Name(), + "agent": climemory.LegacyAgent, + "sources": len(sources), + "drained": res.Drained, + "dupes": res.Dupes, + "skipped": res.Skipped, + "truncate": req.Truncate, + "truncated": truncated, + "kept": kept, + "errors": errText, + }) +} diff --git a/src/pkg/dashboard/api_knowledge_cli_memory_test.go b/src/pkg/dashboard/api_knowledge_cli_memory_test.go new file mode 100644 index 0000000000..b10804f618 --- /dev/null +++ b/src/pkg/dashboard/api_knowledge_cli_memory_test.go @@ -0,0 +1,165 @@ +package dashboard + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "strings" + "testing" +) + +const drainedDraftEntry = "---\ntitle: Webhook retries need the idempotency key\ntype: reference\nlayer: project\nstate: draft\nsource: cli-memory\ncli: claude\nagent: scanner\nmemhash: aaaa\ntags: [cli-memory, cli:claude, memhash:aaaa, agent:scanner]\n---\n\nWebhook retries need the idempotency key.\n" + +// withAutoMemoryVault connects a bead-synth-wiki vault holding one drained +// CLI-memory draft (cli-memory-aaaa) to s and returns its directory. +func withAutoMemoryVault(t *testing.T, s *Server) string { + t.Helper() + dir := filepath.Join(t.TempDir(), "bead-synth-wiki") + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(dir, "cli-memory-aaaa.md"), []byte(drainedDraftEntry), 0o644); err != nil { + t.Fatal(err) + } + if err := s.deps.Knowledge.ConnectVault(dir, "bead-synth-wiki"); err != nil { + t.Fatal(err) + } + return dir +} + +// TestKnowledgeAgentReadsHideAutoMemoryDrafts covers the #17058 exclusion on +// the pull-mode surfaces: an agent-identified TOC, entry or effective read +// never shows a drained draft, even when the request and the agent's scope +// admit drafts, while operator reads list it for review; approving it through +// the state API makes it visible to agents. +func TestKnowledgeAgentReadsHideAutoMemoryDrafts(t *testing.T) { + s := scopedKnowledgeTOCServer(t) + withAutoMemoryVault(t, s) + + for _, tc := range []struct { + target string + want bool + }{ + {"/api/knowledge/toc?include_states=draft", true}, + {"/api/knowledge/toc?agent=scanner&include_states=all", false}, + {"/api/knowledge/toc?agent=reviewer&include_states=all", false}, + } { + code, body := tocGet(t, s, tc.target) + if code != http.StatusOK { + t.Fatalf("%s status = %d", tc.target, code) + } + ids := tocIDs(t, body) + if got := strings.Contains(ids, "cli-memory-aaaa"); got != tc.want { + t.Errorf("%s ids = %q, auto-memory draft listed = %v, want %v", tc.target, ids, got, tc.want) + } + if strings.Contains(tc.target, "scanner") && !strings.Contains(ids, "draft-idea") { + t.Errorf("%s ids = %q: the agent's ordinary drafts must still be admitted", tc.target, ids) + } + } + + if code, _ := tocGet(t, s, "/api/knowledge/entry/cli-memory-aaaa?include_states=draft"); code != http.StatusOK { + t.Errorf("operator entry read status = %d, want 200", code) + } + if code, _ := tocGet(t, s, "/api/knowledge/entry/cli-memory-aaaa?agent=reviewer&include_states=draft"); code != http.StatusNotFound { + t.Errorf("agent entry read status = %d, want 404", code) + } + if _, body := tocGet(t, s, "/api/knowledge/search?tag=cli-memory&include_states=draft"); body["count"] != float64(1) { + t.Errorf("operator search for auto-memory drafts = %v, want one result", body) + } + _, eff := tocGet(t, s, "/api/knowledge/effective?agent=scanner&include_states=all") + excluded, _ := json.Marshal(eff["excluded"]) + if !strings.Contains(string(excluded), `"id":"cli-memory-aaaa"`) || !strings.Contains(string(excluded), `"reason":"lifecycle"`) { + t.Errorf("effective view excluded = %s, want cli-memory-aaaa with reason lifecycle", excluded) + } + + if rec := doKnowledgeStatePut(s, "cli-memory-aaaa", "alice", true, `{"state":"approved","reason":"reviewed"}`); rec.Code != http.StatusOK { + t.Fatalf("approve status = %d body=%s", rec.Code, rec.Body.String()) + } + if _, body := tocGet(t, s, "/api/knowledge/toc?agent=scanner"); !strings.Contains(tocIDs(t, body), "cli-memory-aaaa") { + t.Errorf("approved auto-memory entry missing from the agent TOC: %s", tocIDs(t, body)) + } +} + +func postLegacyDrain(s *Server, body string) (int, map[string]interface{}) { + req := httptest.NewRequest(http.MethodPost, "/api/knowledge/cli-memory/drain-legacy", strings.NewReader(body)) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("X-Hive-User", "alice") + markOwnerRequest(req) + rec := httptest.NewRecorder() + s.mux.ServeHTTP(rec, req) + var out map[string]interface{} + _ = json.Unmarshal(rec.Body.Bytes(), &out) + return rec.Code, out +} + +func TestKnowledgeDrainLegacyMemory(t *testing.T) { + projects := t.TempDir() + prev := legacyClaudeProjectsDir + legacyClaudeProjectsDir = projects + t.Cleanup(func() { legacyClaudeProjectsDir = prev }) + memFile := filepath.Join(projects, "-data-agents-scanner-hivecommons-hive", "memory", "MEMORY.md") + if err := os.MkdirAll(filepath.Dir(memFile), 0o755); err != nil { + t.Fatal(err) + } + const memory = "- Never force-push a shared branch.\n" + if err := os.WriteFile(memFile, []byte(memory), 0o644); err != nil { + t.Fatal(err) + } + + s := knowledgeTOCServer(t) + if code, _ := postLegacyDrain(s, ""); code != http.StatusConflict { + t.Fatalf("drain without the bead-synth vault status = %d, want 409", code) + } + vault := withAutoMemoryVault(t, s) + s.deps.Config.Project.Repos = []string{"hivecommons/hive"} + + code, resp := postLegacyDrain(s, "") + if code != http.StatusOK || resp["drained"] != float64(1) || resp["agent"] != "shared" || resp["truncate"] != false { + t.Fatalf("first drain = %d %v", code, resp) + } + if b, _ := os.ReadFile(memFile); string(b) != memory { + t.Fatalf("memory file changed without truncate: %q", b) + } + entries, _ := filepath.Glob(filepath.Join(vault, "cli-memory-*.md")) + var drained string + for _, e := range entries { + if b, _ := os.ReadFile(e); strings.Contains(string(b), "force-push") { + drained = string(b) + } + } + for _, want := range []string{"state: draft", "agent:shared", "repo:hivecommons/hive"} { + if !strings.Contains(drained, want) { + t.Fatalf("drained entry missing %q:\n%s", want, drained) + } + } + if _, body := tocGet(t, s, "/api/knowledge/toc?agent=reviewer&include_states=all"); strings.Contains(compactJSON(body), "force-push") { + t.Fatal("legacy draft visible to an agent") + } + + code, resp = postLegacyDrain(s, `{"truncate":true}`) + if code != http.StatusOK || resp["drained"] != float64(0) || resp["dupes"] != float64(1) { + t.Fatalf("second drain = %d %v", code, resp) + } + if got := compactJSON(resp["truncated"]); got != `["`+memFile+`"]` { + t.Fatalf("truncated = %s, want [%s]", got, memFile) + } + if b, _ := os.ReadFile(memFile); len(b) != 0 { + t.Fatalf("memory file not emptied: %q", b) + } + audits := knowledgeStateAudit(s, "knowledge_drain_legacy_memory") + // Recent lists newest first: [0] is the truncating run. + if len(audits) != 2 || !strings.Contains(audits[0].Detail, "truncate=true") || !strings.Contains(audits[1].Detail, "truncate=false") || audits[0].User != "alice" { + t.Fatalf("audit = %+v", audits) + } + + if code, _ := postLegacyDrain(s, "{not json"); code != http.StatusBadRequest { + t.Fatalf("bad body status = %d, want 400", code) + } +} + +func compactJSON(v interface{}) string { + b, _ := json.Marshal(v) + return string(b) +} diff --git a/src/pkg/dashboard/api_knowledge_toc.go b/src/pkg/dashboard/api_knowledge_toc.go index 2ee4951073..1c8634a325 100644 --- a/src/pkg/dashboard/api_knowledge_toc.go +++ b/src/pkg/dashboard/api_knowledge_toc.go @@ -12,7 +12,9 @@ import ( // knowledgeTOCScope parses the scope query shared by the TOC and full-read // endpoints: layers, repos, types and tags (comma-separated allow-lists) plus // include_states for operators who need draft/deprecated/superseded entries. -// The default is approved knowledge only (#11102). +// The default is approved knowledge only (#11102). A request naming an agent +// with ?agent= never sees a drained CLI-memory draft, whatever include_states +// says (#17058); only operator reads list them for review. func knowledgeTOCScope(r *http.Request) (knowledge.TOCScope, error) { q := r.URL.Query() include, err := knowledge.ParseLifecycleStates(q.Get("include_states")) @@ -20,10 +22,11 @@ func knowledgeTOCScope(r *http.Request) (knowledge.TOCScope, error) { return knowledge.TOCScope{}, err } scope := knowledge.TOCScope{ - Repos: splitCSV(q.Get("repos")), - Types: splitCSV(q.Get("types")), - Tags: splitCSV(q.Get("tags")), - IncludeStates: include, + Repos: splitCSV(q.Get("repos")), + Types: splitCSV(q.Get("types")), + Tags: splitCSV(q.Get("tags")), + IncludeStates: include, + HideAutoMemoryDrafts: strings.TrimSpace(q.Get("agent")) != "", } for _, l := range splitCSV(q.Get("layers")) { scope.Layers = append(scope.Layers, knowledge.LayerType(strings.ToLower(l))) diff --git a/src/pkg/dashboard/knowledge_auto_memory_ui_test.go b/src/pkg/dashboard/knowledge_auto_memory_ui_test.go new file mode 100644 index 0000000000..89cbbae0b6 --- /dev/null +++ b/src/pkg/dashboard/knowledge_auto_memory_ui_test.go @@ -0,0 +1,107 @@ +package dashboard + +import ( + "os/exec" + "strings" + "testing" +) + +// knowledgeAutoMemoryUIScript drives the knowledge view's auto-memory review +// (#17058) against the generated index.html: the filter lists drained drafts +// only, rows show the agent: tags, an owner gets approve/discard backed by +// PUT /api/knowledge/entry/{id}/state, and a non-owner gets no buttons. +func knowledgeAutoMemoryUIScript(t *testing.T) string { + t.Helper() + b, err := staticFS.ReadFile("static/index.html") + if err != nil { + t.Fatal(err) + } + html := string(b) + section := func(start, end string) string { + t.Helper() + i := strings.Index(html, start) + if i < 0 { + t.Fatalf("missing %s", start) + } + j := strings.Index(html[i:], end) + if j < 0 { + t.Fatalf("missing %s", end) + } + return html[i : i+j] + } + return ` +const assert = require('node:assert/strict'); +let _kbFacts = [], _kbPageSize = 50, _kbPageOffset = 0, _kbServerPaged = false, + _kbHasMore = false, _kbRequest = 0, _kbSelectedFact = null, + _kbSearchQuery = '', _kbSelectedLayer = 'auto-memory', _kbSelectedType = ''; +const el = {innerHTML: ''}; +const document = {getElementById: () => el}; +const kbIsDividerOnlyFact = () => false; +const escapeHtml = s => String(s); +const kbCleanFactTitle = s => s; +const kbCleanFactPreview = s => s; +const kbConfidenceBadge = () => ''; +const confColor = () => 'green'; +let owner = true, confirmed = true, alerts = [], statsFetched = 0; +const viewerIsOwner = () => owner; +const hiveConfirm = async () => confirmed; +const hiveAlert = async msg => { alerts.push(msg); }; +const _inceptionAuthHeaders = () => ({'Content-Type': 'application/json'}); +const fetchKnowledgeStats = () => { statsFetched++; }; +` + section(" function kbSearch() {", " async function kbReadFact(") + + section(" function renderKnowledgeFacts() {", " function renderKnowledgeDetail()") + ` +(async () => { + const drained = {slug: 'cli-memory-aaaa', title: 'Use go test -run', state: 'draft', + tags: ['cli-memory', 'cli:claude', 'memhash:aaaa', 'agent:scanner', 'agent:developer']}; + const approved = {slug: 'cli-memory-bbbb', title: 'Approved memory', state: 'approved', tags: ['cli-memory', 'agent:scanner']}; + const calls = []; + global.fetch = async (url, opts) => { + calls.push({url, opts}); + if (opts && opts.method === 'PUT') return {ok: true, json: async () => ({ok: true})}; + return {ok: true, json: async () => ({results: [drained, approved]})}; + }; + await kbSearch(); + assert.match(calls[0].url, /^\/api\/knowledge\/search\?tag=cli-memory&include_states=draft/); + assert.deepEqual(_kbFacts.map(f => f.slug), ['cli-memory-aaaa'], 'only drafts are listed for review'); + assert.ok(el.innerHTML.includes('agent scanner') && el.innerHTML.includes('agent developer'), el.innerHTML); + assert.match(el.innerHTML, /data-action="kbAutoMemoryReview" data-arg0="cli-memory-aaaa" data-arg1="approved"/); + assert.match(el.innerHTML, /data-action="kbAutoMemoryReview" data-arg0="cli-memory-aaaa" data-arg1="deprecated"/); + + await kbAutoMemoryReview('cli-memory-aaaa', 'approved'); + const put = calls.find(c => c.opts && c.opts.method === 'PUT'); + assert.equal(put.url, '/api/knowledge/entry/cli-memory-aaaa/state'); + assert.equal(JSON.parse(put.opts.body).state, 'approved'); + assert.equal(statsFetched, 1); + assert.deepEqual(alerts, []); + + await kbAutoMemoryReview('cli-memory-aaaa', 'deprecated'); + const discard = calls.filter(c => c.opts && c.opts.method === 'PUT')[1]; + assert.equal(JSON.parse(discard.opts.body).state, 'deprecated', 'discard deprecates so the drain never re-drafts it'); + + confirmed = false; + const before = calls.length; + await kbAutoMemoryReview('cli-memory-aaaa', 'approved'); + assert.equal(calls.length, before, 'a cancelled confirm sends nothing'); + + owner = false; + renderKnowledgeFacts(); + assert.ok(el.innerHTML.includes('agent scanner')); + assert.ok(!el.innerHTML.includes('kbAutoMemoryReview'), 'non-owners get no review buttons'); + + _kbFacts = [{slug: 'plain', title: 'Plain fact', state: 'draft', tags: ['agent:scanner']}]; + owner = true; + renderKnowledgeFacts(); + assert.ok(!el.innerHTML.includes('kbAutoMemoryReview') && !el.innerHTML.includes('agent scanner'), 'only drained facts get review controls'); +})().catch(e => {console.error(e); process.exit(1);}); +` +} + +func TestKnowledgeAutoMemoryReviewUI(t *testing.T) { + node, err := exec.LookPath("node") + if err != nil { + t.Skip("node unavailable") + } + if out, err := exec.Command(node, "-e", knowledgeAutoMemoryUIScript(t)).CombinedOutput(); err != nil { + t.Fatalf("auto-memory review UI: %v\n%s", err, out) + } +} diff --git a/src/pkg/dashboard/owner_only_handlers_deny_test.go b/src/pkg/dashboard/owner_only_handlers_deny_test.go index bb972e079b..2dc33ccc7b 100644 --- a/src/pkg/dashboard/owner_only_handlers_deny_test.go +++ b/src/pkg/dashboard/owner_only_handlers_deny_test.go @@ -104,6 +104,7 @@ func TestV4OwnerOnlyHandlerGapsRejectUnverifiedOwners(t *testing.T) { {"knowledge connectors sync", http.MethodPost, "/api/config/knowledge/connectors/docs/sync", srv.handleKnowledgeConnectorsSync}, {"knowledge connectors validate", http.MethodPost, "/api/config/knowledge/connectors/validate", srv.handleKnowledgeConnectorsValidate}, {"knowledge entry state", http.MethodPut, "/api/knowledge/entry/old-way/state", srv.handleKnowledgeEntryState}, + {"knowledge legacy memory drain", http.MethodPost, "/api/knowledge/cli-memory/drain-legacy", srv.handleKnowledgeDrainLegacyMemory}, {"knowledge public", http.MethodPut, "/api/knowledge/public", srv.handlePublicKnowledgePut}, {"knowledge toggle", http.MethodPut, "/api/knowledge/enabled", srv.handleKnowledgeToggle}, {"nous abort", http.MethodPost, "/api/nous/abort", srv.handleNousAbort}, diff --git a/src/pkg/dashboard/static-src/js/knowledge.js b/src/pkg/dashboard/static-src/js/knowledge.js index a60de19e0d..8faebe876b 100644 --- a/src/pkg/dashboard/static-src/js/knowledge.js +++ b/src/pkg/dashboard/static-src/js/knowledge.js @@ -306,6 +306,12 @@ renderKnowledgeFacts(); } + // Auto-memory review (#17058): drafts the CLI-memory drain wrote. The + // search API is an operator read, so include_states=draft lists them; + // no agent read ever does until one is approved. + const KB_AUTO_MEMORY_VIEW = 'auto-memory'; + const KB_AUTO_MEMORY_TAG = 'cli-memory'; + async function kbLoadFacts(offset) { const request = ++_kbRequest; const query = _kbSearchQuery; @@ -315,6 +321,9 @@ if (query) { url = '/api/knowledge/search?q=' + encodeURIComponent(query) + '&limit=50'; if (typeFilter) url += '&type=' + encodeURIComponent(typeFilter); + } else if (layer === KB_AUTO_MEMORY_VIEW) { + url = '/api/knowledge/search?tag=' + KB_AUTO_MEMORY_TAG + '&include_states=draft&limit=200'; + if (typeFilter) url += '&type=' + encodeURIComponent(typeFilter); } else if (layer && layer !== 'all') { // Check if this is a vault, document, or standard layer type const standardLayers = ['personal','project','org','community']; @@ -342,6 +351,7 @@ _kbPageOffset = offset; _kbHasMore = !!data.has_more; _kbFacts = Array.isArray(data) ? data : (data.results || data.facts || []); + if (!query && layer === KB_AUTO_MEMORY_VIEW) _kbFacts = _kbFacts.filter(f => f.state === 'draft'); _kbSelectedFact = null; renderKnowledgeFacts(); } catch (e) { @@ -1096,6 +1106,7 @@ html += '
'; // Aggregate row stays on top as the filter reset (kbSelectLayer keys on the 'All Layers' text) html += ``; + html += ``; for (const l of layers) { const isGitSource = l.type && l.type.startsWith('git_source:'); const icon = KB_LAYER_ICONS[l.type] || (isGitSource ? '📄' : '📂'); @@ -1321,6 +1332,7 @@ html += `${escapeHtml(f.type || 'unknown')}`; html += `${escapeHtml(f.layer || '')}`; if (f.status) html += `${escapeHtml(f.status)}`; + html += kbAutoMemoryRowHTML(f); html += '
'; } if (_kbPageOffset > 0 || hasNext) { @@ -1332,6 +1344,44 @@ el.innerHTML = html; } + function kbIsAutoMemory(f) { + return (f.tags || []).some(t => String(t).trim().toLowerCase() === KB_AUTO_MEMORY_TAG); + } + + // Agent tags of a drained CLI-memory fact, plus approve and discard for + // an owner while it is still a draft. Discard deprecates rather than + // deletes, so the drain's content hash keeps it from being re-drafted. + function kbAutoMemoryRowHTML(f) { + if (!kbIsAutoMemory(f)) return ''; + let html = ''; + for (const t of (f.tags || [])) { + const m = /^agent:(.+)$/i.exec(String(t).trim()); + if (m) html += `agent ${escapeHtml(m[1])}`; + } + if (f.state === 'draft' && viewerIsOwner()) { + const slug = escapeHtml(f.slug || ''); + html += ``; + html += ``; + } + return html; + } + + async function kbAutoMemoryReview(slug, state) { + const question = state === 'approved' + ? 'Approve "' + slug + '"? It was written by an agent, and once approved it is injected into the kicks of every agent whose scope includes it.' + : 'Discard "' + slug + '"? It is marked deprecated, no agent receives it, and the drain will not re-draft it.'; + if (!(await hiveConfirm(question))) return; + try { + const r = await fetch('/api/knowledge/entry/' + encodeURIComponent(slug) + '/state', { + method: 'PUT', headers: _inceptionAuthHeaders(), + body: JSON.stringify({ state, reason: 'auto-memory review (dashboard)' }), + }); + if (!r.ok) { const e = await r.json().catch(() => ({})); await hiveAlert(e.error || 'Failed to change state'); return; } + fetchKnowledgeStats(); + kbSearch(); + } catch (e) { await hiveAlert('Error: ' + e.message); } + } + function renderKnowledgeDetail() { const el = document.getElementById('kb-fact-detail'); if (!el || !_kbSelectedFact) { if (el) el.innerHTML = ''; return; } diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index 25de96754d..0605ab4634 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -41893,6 +41893,12 @@

All labels

renderKnowledgeFacts(); } + // Auto-memory review (#17058): drafts the CLI-memory drain wrote. The + // search API is an operator read, so include_states=draft lists them; + // no agent read ever does until one is approved. + const KB_AUTO_MEMORY_VIEW = 'auto-memory'; + const KB_AUTO_MEMORY_TAG = 'cli-memory'; + async function kbLoadFacts(offset) { const request = ++_kbRequest; const query = _kbSearchQuery; @@ -41902,6 +41908,9 @@

All labels

if (query) { url = '/api/knowledge/search?q=' + encodeURIComponent(query) + '&limit=50'; if (typeFilter) url += '&type=' + encodeURIComponent(typeFilter); + } else if (layer === KB_AUTO_MEMORY_VIEW) { + url = '/api/knowledge/search?tag=' + KB_AUTO_MEMORY_TAG + '&include_states=draft&limit=200'; + if (typeFilter) url += '&type=' + encodeURIComponent(typeFilter); } else if (layer && layer !== 'all') { // Check if this is a vault, document, or standard layer type const standardLayers = ['personal','project','org','community']; @@ -41929,6 +41938,7 @@

All labels

_kbPageOffset = offset; _kbHasMore = !!data.has_more; _kbFacts = Array.isArray(data) ? data : (data.results || data.facts || []); + if (!query && layer === KB_AUTO_MEMORY_VIEW) _kbFacts = _kbFacts.filter(f => f.state === 'draft'); _kbSelectedFact = null; renderKnowledgeFacts(); } catch (e) { @@ -42683,6 +42693,7 @@

All labels

html += '
'; // Aggregate row stays on top as the filter reset (kbSelectLayer keys on the 'All Layers' text) html += ``; + html += ``; for (const l of layers) { const isGitSource = l.type && l.type.startsWith('git_source:'); const icon = KB_LAYER_ICONS[l.type] || (isGitSource ? '📄' : '📂'); @@ -42908,6 +42919,7 @@

All labels

html += `${escapeHtml(f.type || 'unknown')}`; html += `${escapeHtml(f.layer || '')}`; if (f.status) html += `${escapeHtml(f.status)}`; + html += kbAutoMemoryRowHTML(f); html += '
'; } if (_kbPageOffset > 0 || hasNext) { @@ -42919,6 +42931,44 @@

All labels

el.innerHTML = html; } + function kbIsAutoMemory(f) { + return (f.tags || []).some(t => String(t).trim().toLowerCase() === KB_AUTO_MEMORY_TAG); + } + + // Agent tags of a drained CLI-memory fact, plus approve and discard for + // an owner while it is still a draft. Discard deprecates rather than + // deletes, so the drain's content hash keeps it from being re-drafted. + function kbAutoMemoryRowHTML(f) { + if (!kbIsAutoMemory(f)) return ''; + let html = ''; + for (const t of (f.tags || [])) { + const m = /^agent:(.+)$/i.exec(String(t).trim()); + if (m) html += `agent ${escapeHtml(m[1])}`; + } + if (f.state === 'draft' && viewerIsOwner()) { + const slug = escapeHtml(f.slug || ''); + html += ``; + html += ``; + } + return html; + } + + async function kbAutoMemoryReview(slug, state) { + const question = state === 'approved' + ? 'Approve "' + slug + '"? It was written by an agent, and once approved it is injected into the kicks of every agent whose scope includes it.' + : 'Discard "' + slug + '"? It is marked deprecated, no agent receives it, and the drain will not re-draft it.'; + if (!(await hiveConfirm(question))) return; + try { + const r = await fetch('/api/knowledge/entry/' + encodeURIComponent(slug) + '/state', { + method: 'PUT', headers: _inceptionAuthHeaders(), + body: JSON.stringify({ state, reason: 'auto-memory review (dashboard)' }), + }); + if (!r.ok) { const e = await r.json().catch(() => ({})); await hiveAlert(e.error || 'Failed to change state'); return; } + fetchKnowledgeStats(); + kbSearch(); + } catch (e) { await hiveAlert('Error: ' + e.message); } + } + function renderKnowledgeDetail() { const el = document.getElementById('kb-fact-detail'); if (!el || !_kbSelectedFact) { if (el) el.innerHTML = ''; return; } diff --git a/src/pkg/hivectl/commands/knowledge.go b/src/pkg/hivectl/commands/knowledge.go index a25acbde69..3ddc3d6775 100644 --- a/src/pkg/hivectl/commands/knowledge.go +++ b/src/pkg/hivectl/commands/knowledge.go @@ -41,6 +41,7 @@ func newKnowledgeCommand(env *commandEnv) *cobra.Command { knowledge.AddCommand(knowledgeWriteCommand(env, "update")) knowledge.AddCommand(knowledgeDeleteCommand(env)) knowledge.AddCommand(knowledgeStateCommand(env)) + knowledge.AddCommand(knowledgeDrainMemoryCommand(env)) knowledge.AddCommand(knowledgeImportCommand(env)) knowledge.AddCommand(knowledgeExportCommand(env)) knowledge.AddCommand(knowledgeGraphCommand(env)) @@ -246,6 +247,32 @@ func knowledgeStateCommand(env *commandEnv) *cobra.Command { return command } +func knowledgeDrainMemoryCommand(env *commandEnv) *cobra.Command { + var legacy, truncate bool + command := &cobra.Command{ + Use: "drain-memory --legacy [--truncate]", + Short: "Drain the shared home's legacy Claude memory into draft knowledge (owner only, audited)", + Long: "Drains every /data/home/.claude/projects/*/memory store left behind by per-agent CLI homes\n" + + "into draft entries in the bead-synth-wiki vault, tagged cli-memory and agent:shared and\n" + + "deduplicated by content hash. Drafts reach no agent until approved with\n" + + "'hivectl knowledge state approved'. Memory files are emptied only with --truncate,\n" + + "and only files whose every fact is now stored. Per-agent stores drain at kick time\n" + + "(agents.cli_memory.drain_to_knowledge), so --legacy is required.", + Args: argsNone(), + Example: " hivectl knowledge drain-memory --legacy\n" + + " hivectl knowledge drain-memory --legacy --truncate --output json", + RunE: func(cmd *cobra.Command, _ []string) error { + if !legacy { + return &usageError{message: "--legacy is required: per-agent CLI memory drains at kick time (agents.cli_memory.drain_to_knowledge)"} + } + return env.do(cmd, http.MethodPost, "/api/knowledge/cli-memory/drain-legacy", map[string]any{"truncate": truncate}) + }, + } + command.Flags().BoolVar(&legacy, "legacy", false, "drain the shared /data/home Claude memory store (required)") + command.Flags().BoolVar(&truncate, "truncate", false, "empty each memory file whose facts are all stored") + return command +} + func knowledgeImportCommand(env *commandEnv) *cobra.Command { var file, format, layer string var stdin bool diff --git a/src/pkg/hivectl/commands/knowledge_more_test.go b/src/pkg/hivectl/commands/knowledge_more_test.go index 59ca267ad4..584caff8a4 100644 --- a/src/pkg/hivectl/commands/knowledge_more_test.go +++ b/src/pkg/hivectl/commands/knowledge_more_test.go @@ -371,3 +371,44 @@ func TestKnowledgeStateSendsLifecycleChange(t *testing.T) { } } } + +// TestKnowledgeDrainMemoryLegacy covers drain-memory: --legacy is required +// (per-agent stores drain at kick time) and --truncate is forwarded, default +// off, to the legacy drain endpoint. +func TestKnowledgeDrainMemoryLegacy(t *testing.T) { + refuse := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + t.Fatalf("drain-memory without --legacy reached the server: %s %s", r.Method, r.URL.Path) + })) + _, _, err := execute(t, refuse, "", "knowledge", "drain-memory") + refuse.Close() + if err == nil || ExitCode(err) != ExitUsage { + t.Fatalf("drain-memory without --legacy err = %v, want usage error", err) + } + + for _, tc := range []struct { + args []string + want bool + }{ + {[]string{"--legacy"}, false}, + {[]string{"--legacy", "--truncate"}, true}, + } { + var got map[string]any + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodPost || r.URL.Path != "/api/knowledge/cli-memory/drain-legacy" { + t.Fatalf("request = %s %s", r.Method, r.URL.Path) + } + if err := json.NewDecoder(r.Body).Decode(&got); err != nil { + t.Fatal(err) + } + w.Header().Set("Content-Type", "application/json") + io.WriteString(w, `{"drained":1}`) + })) + if _, _, err := execute(t, server, "", append([]string{"knowledge", "drain-memory"}, tc.args...)...); err != nil { + t.Fatalf("%v: %v", tc.args, err) + } + server.Close() + if len(got) != 1 || got["truncate"] != tc.want { + t.Fatalf("%v: body = %v, want truncate=%v", tc.args, got, tc.want) + } + } +} diff --git a/src/pkg/knowledge/api.go b/src/pkg/knowledge/api.go index 8788670820..8e6ce4c5c6 100644 --- a/src/pkg/knowledge/api.go +++ b/src/pkg/knowledge/api.go @@ -453,8 +453,12 @@ func (k *KnowledgeAPI) SetEntryState(id string, state LifecycleState, superseded return change, nil } -// writableVaultHolding returns the first non-reserved vault holding id and -// the entry as currently stored. +// writableVaultHolding returns the first vault holding id whose entries a +// lifecycle change may rewrite, and the entry as currently stored. The +// reserved bead-synth vault is skipped except for drained CLI-memory entries +// (`source: cli-memory`, #17058): the drain writes those once and never +// rewrites them, so approving or discarding one cannot fight the +// synthesizer, and review is the only way a drained draft is ever primed. func (k *KnowledgeAPI) writableVaultHolding(id string) (*FileStore, *Fact) { if id == "" { return nil, nil @@ -463,16 +467,31 @@ func (k *KnowledgeAPI) writableVaultHolding(id string) (*FileStore, *Fact) { vaults := append([]*FileStore(nil), k.vaults...) k.mu.RUnlock() for _, v := range vaults { - if v.Name() == reservedVaultName { + f, err := v.ReadPage(id) + if err != nil { continue } - if f, err := v.ReadPage(id); err == nil { - return v, f + if v.Name() == reservedVaultName && !strings.EqualFold(strings.TrimSpace(f.Origin), AutoMemoryTag) { + continue } + return v, f } return nil, nil } +// AutoMemoryVault returns the connected bead-synth vault that CLI-memory +// drains write their drafts into, or nil when it is not connected. +func (k *KnowledgeAPI) AutoMemoryVault() *FileStore { + k.mu.RLock() + defer k.mu.RUnlock() + for _, v := range k.vaults { + if v.Name() == reservedVaultName { + return v + } + } + return nil +} + // DeleteFact removes a fact from the specified layer. func (k *KnowledgeAPI) DeleteFact(ctx context.Context, layer LayerType, slug string) error { client := k.clientForLayer(layer) diff --git a/src/pkg/knowledge/auto_memory.go b/src/pkg/knowledge/auto_memory.go new file mode 100644 index 0000000000..30c1514007 --- /dev/null +++ b/src/pkg/knowledge/auto_memory.go @@ -0,0 +1,36 @@ +package knowledge + +import "strings" + +// AutoMemoryTag marks a knowledge entry drained from a coding CLI's own +// memory store (#17033). The drain writes it both as a tag and as the +// entry's `source:` frontmatter. +const AutoMemoryTag = "cli-memory" + +// IsAutoMemory reports whether f was drained from a CLI memory store: it +// carries the AutoMemoryTag tag or `source: cli-memory`. Either marker is +// enough, so the agent-facing exclusion fails closed. +func IsAutoMemory(f Fact) bool { + return strings.EqualFold(strings.TrimSpace(f.Origin), AutoMemoryTag) || hasTagFold(f.Tags, AutoMemoryTag) +} + +// hasTagFold reports whether tags holds want, ignoring case and surrounding +// space. +func hasTagFold(tags []string, want string) bool { + for _, t := range tags { + if strings.EqualFold(strings.TrimSpace(t), want) { + return true + } + } + return false +} + +// IsAutoMemoryDraft reports whether f is a drained CLI-memory fact that is +// still a draft. Such a fact is agent-written text nobody has reviewed, so it +// never reaches an agent: not the kick primer, not the knowledge advisor, not +// an agent-identified TOC or entry read, whatever include_states the agent's +// knowledge.agent_scopes entry or the primer config admits (#17058). Only an +// operator approving it through the lifecycle API makes it primable. +func IsAutoMemoryDraft(f Fact) bool { + return f.EffectiveState() == StateDraft && IsAutoMemory(f) +} diff --git a/src/pkg/knowledge/auto_memory_test.go b/src/pkg/knowledge/auto_memory_test.go new file mode 100644 index 0000000000..18b45e556b --- /dev/null +++ b/src/pkg/knowledge/auto_memory_test.go @@ -0,0 +1,95 @@ +package knowledge + +import ( + "errors" + "os" + "path/filepath" + "testing" +) + +func slugSet(facts []Fact) map[string]bool { + out := make(map[string]bool, len(facts)) + for _, f := range facts { + out[f.Slug] = true + } + return out +} + +// TestAutoMemoryDraftsNeverReachAgentFilters pins the #17058 hard exclusion: +// a drained CLI-memory draft passes the operator filter when drafts are asked +// for, but no agent-path filter admits it, whatever include_states or author +// match would admit any other draft. Once approved it is ordinary knowledge. +func TestAutoMemoryDraftsNeverReachAgentFilters(t *testing.T) { + tagged := Fact{Slug: "mem-tagged", State: StateDraft, Author: "scanner", Tags: []string{"agent:scanner", "CLI-Memory"}} + sourced := Fact{Slug: "mem-sourced", State: StateDraft, Author: "scanner", Origin: "cli-memory"} + approvedMem := Fact{Slug: "mem-approved", State: StateApproved, Tags: []string{AutoMemoryTag}} + ownDraft := Fact{Slug: "own-draft", State: StateDraft, Author: "scanner"} + facts := []Fact{tagged, sourced, approvedMem, ownDraft} + + operator := slugSet(FilterByLifecycle(facts, []LifecycleState{StateDraft})) + for _, slug := range []string{"mem-tagged", "mem-sourced", "mem-approved", "own-draft"} { + if !operator[slug] { + t.Errorf("operator filter with include draft dropped %s; drafts must stay reviewable", slug) + } + } + + kick := slugSet(FilterByLifecycleFor(facts, AllLifecycleStates, []string{"scanner"})) + if kick["mem-tagged"] || kick["mem-sourced"] { + t.Errorf("kick filter admitted an auto-memory draft: %v", kick) + } + if !kick["mem-approved"] || !kick["own-draft"] { + t.Errorf("kick filter dropped an approved auto-memory fact or an ordinary own draft: %v", kick) + } + + agent := AgentScope(nil, nil, nil, nil, []string{"all"}) + request := TOCScope{IncludeStates: AllLifecycleStates} + for _, f := range []Fact{tagged, sourced} { + if got := agent.ExclusionReason(f); got != ExcludedLifecycle { + t.Errorf("agent scope ExclusionReason(%s) = %q, want %q", f.Slug, got, ExcludedLifecycle) + } + if !request.InScope(f) { + t.Errorf("operator scope with all states hid %s", f.Slug) + } + } + if !agent.InScope(approvedMem) || !agent.InScope(ownDraft) { + t.Error("agent scope with all states must admit approved auto-memory and ordinary drafts") + } +} + +// TestSetEntryStateReviewsDrainedEntriesInBeadSynthVault proves the review +// path the drain depends on: a drained entry in the reserved bead-synth vault +// can be approved through SetEntryState, while a synthesizer entry in the +// same vault stays off-limits. +func TestSetEntryStateReviewsDrainedEntriesInBeadSynthVault(t *testing.T) { + dir := t.TempDir() + write := func(name, content string) { + t.Helper() + if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644); err != nil { + t.Fatal(err) + } + } + write("cli-memory-aaaa.md", "---\ntitle: Run go test with -run\ntype: reference\nstate: draft\nsource: cli-memory\ntags: [cli-memory, agent:scanner]\n---\n\nRun go test with -run.\n") + write("synth.md", "---\ntitle: Synthesized fact\ntype: gotcha\n---\n\nFrom a bead.\n") + + api := NewKnowledgeAPI(nil, KnowledgeConfig{Enabled: true, Engine: "file"}, testLogger()) + if api.AutoMemoryVault() != nil { + t.Fatal("AutoMemoryVault before the vault is connected") + } + if err := api.ConnectVault(dir, reservedVaultName); err != nil { + t.Fatal(err) + } + if v := api.AutoMemoryVault(); v == nil || v.RootDir() != dir { + t.Fatalf("AutoMemoryVault = %v, want the bead-synth vault at %s", v, dir) + } + + change, err := api.SetEntryState("cli-memory-aaaa", StateApproved, "") + if err != nil { + t.Fatalf("approving a drained entry: %v", err) + } + if change.Previous != StateDraft || change.Fact.EffectiveState() != StateApproved || change.Channel != reservedVaultName { + t.Fatalf("change = %+v (state %s)", change, change.Fact.EffectiveState()) + } + if _, err := api.SetEntryState("synth", StateDeprecated, ""); !errors.Is(err, ErrEntryNotWritable) { + t.Fatalf("synthesizer entry state change err = %v, want ErrEntryNotWritable", err) + } +} diff --git a/src/pkg/knowledge/climemory/drain.go b/src/pkg/knowledge/climemory/drain.go index de8ed2e8ad..411ce362fd 100644 --- a/src/pkg/knowledge/climemory/drain.go +++ b/src/pkg/knowledge/climemory/drain.go @@ -18,8 +18,9 @@ import ( const ( // SourceTag marks every drained entry; `source: cli-memory` is also - // written as frontmatter so the dashboard filter and the tag agree. - SourceTag = "cli-memory" + // written as frontmatter so the dashboard filter and the tag agree. The + // knowledge package keys the agent-facing draft exclusion on it. + SourceTag = knowledge.AutoMemoryTag // HashKey is the frontmatter key (and tag prefix) carrying the SHA-256 of // the normalised fact body; it is what makes repeated drains idempotent. HashKey = "memhash" diff --git a/src/pkg/knowledge/climemory/legacy.go b/src/pkg/knowledge/climemory/legacy.go new file mode 100644 index 0000000000..1fb200c220 --- /dev/null +++ b/src/pkg/knowledge/climemory/legacy.go @@ -0,0 +1,97 @@ +package climemory + +import ( + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" +) + +// LegacyAgent is the agent the one-shot drain of the shared home's Claude +// memory store attributes its entries to (`agent:shared`, #17058). Before +// #17039 every agent wrote into that one tree, so no single agent owns a fact +// found there. +const LegacyAgent = "shared" + +// LegacyClaudeSources lists the Claude auto-memory directories +// /*/memory of the shared home #17039 left behind, in name +// order. A symlinked project or memory directory is skipped; a missing +// projectsDir yields none. +func LegacyClaudeSources(projectsDir string) ([]Source, error) { + entries, err := os.ReadDir(projectsDir) + if err != nil { + if errors.Is(err, fs.ErrNotExist) { + return nil, nil + } + return nil, fmt.Errorf("cli-memory legacy drain: listing %s: %w", projectsDir, err) + } + var out []Source + for _, e := range entries { + if !e.IsDir() { + continue + } + mem := filepath.Join(projectsDir, e.Name(), "memory") + info, err := os.Lstat(mem) + if err != nil || !info.IsDir() { + continue + } + out = append(out, Source{CLI: CLIClaude, Path: mem}) + } + return out, nil +} + +// TruncateDrained empties every memory file under sources whose facts are +// all recorded in the vault (by memhash, in any lifecycle state). A file +// holding a fact the vault lacks — a write failed, the per-drain cap was +// hit — is left as it is and reported in kept, so truncation never loses a +// fact. A non-empty file with no fact to drain (a Claude index of links) +// counts as stored. Already-empty files are in neither list. +func (d *Drainer) TruncateDrained(sources []Source) (truncated, kept []string, err error) { + if d == nil || d.Dir == "" { + return nil, nil, errors.New("cli-memory drain: no target directory") + } + seen, err := existingHashes(d.Dir) + if err != nil { + return nil, nil, err + } + var errs []error + for _, src := range sources { + files, err := memoryFiles(src.Path) + if err != nil { + errs = append(errs, err) + continue + } + for _, file := range files { + content, err := os.ReadFile(file) + if err != nil { + errs = append(errs, fmt.Errorf("cli-memory drain: reading %s: %w", file, err)) + kept = append(kept, file) + continue + } + if len(content) == 0 { + continue + } + if !allStored(ParseFor(src.CLI, string(content)), seen) { + kept = append(kept, file) + continue + } + if err := os.Truncate(file, 0); err != nil { + errs = append(errs, fmt.Errorf("cli-memory drain: truncating %s: %w", file, err)) + kept = append(kept, file) + continue + } + truncated = append(truncated, file) + } + } + return truncated, kept, errors.Join(errs...) +} + +func allStored(facts []Fact, seen map[string]bool) bool { + for _, f := range facts { + if !seen[Hash(f.Body)] { + return false + } + } + return true +} diff --git a/src/pkg/knowledge/climemory/legacy_test.go b/src/pkg/knowledge/climemory/legacy_test.go new file mode 100644 index 0000000000..0583ffc0e5 --- /dev/null +++ b/src/pkg/knowledge/climemory/legacy_test.go @@ -0,0 +1,113 @@ +package climemory + +import ( + "os" + "path/filepath" + "reflect" + "strings" + "testing" +) + +func writeFile(t *testing.T, path, content string) { + t.Helper() + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte(content), 0o644); err != nil { + t.Fatal(err) + } +} + +func TestLegacyClaudeSources(t *testing.T) { + if got, err := LegacyClaudeSources(filepath.Join(t.TempDir(), "missing")); err != nil || got != nil { + t.Fatalf("missing tree = %v, %v; want none", got, err) + } + notDir := filepath.Join(t.TempDir(), "projects") + writeFile(t, notDir, "not a directory") + if _, err := LegacyClaudeSources(notDir); err == nil { + t.Fatal("an unreadable projects tree must be reported, not treated as empty") + } + + projects := t.TempDir() + writeFile(t, filepath.Join(projects, "-data-agents-scanner", "memory", "MEMORY.md"), "- a\n") + writeFile(t, filepath.Join(projects, "-data-agents-developer", "memory", "MEMORY.md"), "- b\n") + writeFile(t, filepath.Join(projects, "-data-agents-nomem", "transcript.jsonl"), "{}\n") + writeFile(t, filepath.Join(projects, "stray.md"), "- c\n") + outside := filepath.Join(t.TempDir(), "memory") + writeFile(t, filepath.Join(outside, "MEMORY.md"), "- d\n") + if err := os.MkdirAll(filepath.Join(projects, "-data-agents-linked"), 0o755); err != nil { + t.Fatal(err) + } + if err := os.Symlink(outside, filepath.Join(projects, "-data-agents-linked", "memory")); err != nil { + t.Fatal(err) + } + if err := os.Symlink(filepath.Dir(outside), filepath.Join(projects, "-data-agents-linkedproject")); err != nil { + t.Fatal(err) + } + + got, err := LegacyClaudeSources(projects) + if err != nil { + t.Fatal(err) + } + want := []Source{ + {CLI: CLIClaude, Path: filepath.Join(projects, "-data-agents-developer", "memory")}, + {CLI: CLIClaude, Path: filepath.Join(projects, "-data-agents-scanner", "memory")}, + } + if !reflect.DeepEqual(got, want) { + t.Fatalf("sources = %v, want %v (symlinked stores and dirs without memory skipped)", got, want) + } +} + +// TestTruncateDrainedOnlyEmptiesFullyStoredFiles proves the --truncate +// contract of the legacy drain: a file is emptied only when every fact in it +// is in the vault, so a fact the vault lacks is never lost. +func TestTruncateDrainedOnlyEmptiesFullyStoredFiles(t *testing.T) { + projects := t.TempDir() + stored := filepath.Join(projects, "-data-agents-scanner", "memory") + pending := filepath.Join(projects, "-data-agents-developer", "memory") + writeFile(t, filepath.Join(stored, "MEMORY.md"), "- Run go test with -run to narrow a failure.\n- The dashboard listens on port 8080.\n") + writeFile(t, filepath.Join(stored, "empty.md"), "") + writeFile(t, filepath.Join(pending, "MEMORY.md"), "- Never force-push a shared branch.\n") + + vault := t.TempDir() + d := &Drainer{Dir: vault, Now: fixedNow} + res := d.Drain(Request{Agent: LegacyAgent, Sources: []Source{{CLI: CLIClaude, Path: stored}}}) + if res.Drained != 2 || len(res.Errors) != 0 { + t.Fatalf("drain = %+v", res) + } + entries, _ := filepath.Glob(filepath.Join(vault, filePrefix+"*.md")) + for _, e := range entries { + b, _ := os.ReadFile(e) + if !strings.Contains(string(b), "agent:"+LegacyAgent) || !strings.Contains(string(b), "state: draft") { + t.Fatalf("legacy entry %s lacks agent:%s or state draft:\n%s", e, LegacyAgent, b) + } + } + + sources := []Source{{CLI: CLIClaude, Path: stored}, {CLI: CLIClaude, Path: pending}} + truncated, kept, err := d.TruncateDrained(sources) + if err != nil { + t.Fatal(err) + } + if want := []string{filepath.Join(stored, "MEMORY.md")}; !reflect.DeepEqual(truncated, want) { + t.Fatalf("truncated = %v, want %v", truncated, want) + } + if want := []string{filepath.Join(pending, "MEMORY.md")}; !reflect.DeepEqual(kept, want) { + t.Fatalf("kept = %v, want %v", kept, want) + } + if b, _ := os.ReadFile(filepath.Join(stored, "MEMORY.md")); len(b) != 0 { + t.Fatalf("stored file not emptied: %q", b) + } + if b, _ := os.ReadFile(filepath.Join(pending, "MEMORY.md")); !strings.Contains(string(b), "force-push") { + t.Fatalf("file with an unstored fact was touched: %q", b) + } + + if _, _, err := (&Drainer{}).TruncateDrained(sources); err == nil { + t.Fatal("TruncateDrained without a vault dir must fail") + } + if _, _, err := (&Drainer{Dir: filepath.Join(t.TempDir(), "missing")}).TruncateDrained(sources); err == nil { + t.Fatal("TruncateDrained with an unreadable vault must fail before touching any file") + } + if b, _ := os.ReadFile(filepath.Join(pending, "MEMORY.md")); len(b) == 0 { + t.Fatal("a failed TruncateDrained emptied a memory file") + } +} diff --git a/src/pkg/knowledge/lifecycle.go b/src/pkg/knowledge/lifecycle.go index 8ac574db3d..b049cb60e6 100644 --- a/src/pkg/knowledge/lifecycle.go +++ b/src/pkg/knowledge/lifecycle.go @@ -99,16 +99,28 @@ func lifecycleAllowed(st LifecycleState, include []LifecycleState) bool { // FilterByLifecycle keeps approved facts plus any facts whose effective state // is listed in include. With a nil/empty include only approved (current) -// knowledge survives. Retained facts have State populated. +// knowledge survives. Retained facts have State populated. It is the operator +// read filter (GET /api/knowledge/search): a drained CLI-memory draft passes +// it when include admits draft, so it can be reviewed. func FilterByLifecycle(facts []Fact, include []LifecycleState) []Fact { - return FilterByLifecycleFor(facts, include, nil) + out := make([]Fact, 0, len(facts)) + for _, f := range facts { + st := f.EffectiveState() + if !lifecycleAllowed(st, include) { + continue + } + f.State = st + out = append(out, f) + } + return out } // FilterByLifecycleFor is FilterByLifecycle that additionally keeps draft // facts authored by one of draftAuthors (#17076). It is the kick-path filter: // the scheduler lists the kicked agent's identities when that agent's // knowledge.agent_scopes entry opts into drafts, so an agent is primed with -// the drafts it wrote while every other draft is still excluded. +// the drafts it wrote while every other draft is still excluded. A drained +// CLI-memory draft never passes it (IsAutoMemoryDraft, #17058). func FilterByLifecycleFor(facts []Fact, include []LifecycleState, draftAuthors []string) []Fact { out := make([]Fact, 0, len(facts)) for _, f := range facts { @@ -123,8 +135,12 @@ func FilterByLifecycleFor(facts []Fact, include []LifecycleState, draftAuthors [ } // lifecycleAllowedFor is lifecycleAllowed plus the author-matched draft rule -// of FilterByLifecycleFor. +// of FilterByLifecycleFor, minus drained CLI-memory drafts, which no include +// list or author match admits on an agent path. func lifecycleAllowedFor(f Fact, st LifecycleState, include []LifecycleState, draftAuthors []string) bool { + if st == StateDraft && IsAutoMemory(f) { + return false + } if lifecycleAllowed(st, include) { return true } diff --git a/src/pkg/knowledge/promote.go b/src/pkg/knowledge/promote.go index 1d0e983845..530a9ed68e 100644 --- a/src/pkg/knowledge/promote.go +++ b/src/pkg/knowledge/promote.go @@ -123,7 +123,9 @@ func (p *Promoter) Promote(ctx context.Context, req PromoteRequest) PromoteResul // AutoPromoteCandidates scans the source layer for facts with confidence above // the configured threshold and returns them as promotion candidates. This is -// used by the curator's scheduled auto-promote flow. +// used by the curator's scheduled auto-promote flow. A page tagged +// AutoMemoryTag is never a candidate (#17058): drained CLI memory is +// agent-written text that moves only when an operator promotes it by hand. func (p *Promoter) AutoPromoteCandidates(ctx context.Context, fromLayer, toLayer LayerType) ([]PromoteRequest, error) { client, ok := p.layers[fromLayer] if !ok { @@ -142,7 +144,7 @@ func (p *Promoter) AutoPromoteCandidates(ctx context.Context, fromLayer, toLayer threshold := p.config.AutoPromoteThreshold var candidates []PromoteRequest for _, page := range pages { - if page.Confidence >= threshold && page.Status == "verified" { + if page.Confidence >= threshold && page.Status == "verified" && !hasTagFold(page.Tags, AutoMemoryTag) { candidates = append(candidates, PromoteRequest{ Slug: page.Slug, FromLayer: fromLayer, diff --git a/src/pkg/knowledge/promote_test.go b/src/pkg/knowledge/promote_test.go index 43811a203e..04e0b15764 100644 --- a/src/pkg/knowledge/promote_test.go +++ b/src/pkg/knowledge/promote_test.go @@ -131,6 +131,8 @@ func TestAutoPromoteCandidates(t *testing.T) { {Slug: "high-conf", Confidence: 0.95, Status: "verified"}, {Slug: "low-conf", Confidence: 0.5, Status: "verified"}, {Slug: "high-but-draft", Confidence: 0.95, Status: "draft"}, + // Drained CLI memory never auto-promotes, however it scores (#17058). + {Slug: "auto-memory", Confidence: 0.99, Status: "verified", Tags: []string{"agent:scanner", " CLI-Memory "}}, }, } w.Header().Set("Content-Type", "application/json") diff --git a/src/pkg/knowledge/toc.go b/src/pkg/knowledge/toc.go index d8b1b2b054..1198aae001 100644 --- a/src/pkg/knowledge/toc.go +++ b/src/pkg/knowledge/toc.go @@ -71,6 +71,11 @@ type TOCScope struct { // base agent and the hive's owner logins when the agent's agent_scopes // entry lists draft in include_states. TOC and API reads leave it empty. DraftAuthors []string + // HideAutoMemoryDrafts drops drained CLI-memory drafts (IsAutoMemoryDraft) + // whatever IncludeStates admits (#17058). AgentScope sets it, and the + // dashboard sets it on every agent-identified (?agent=) TOC, entry and + // effective read; operator reads leave it off so drafts can be reviewed. + HideAutoMemoryDrafts bool } // ListsDraft reports whether an include_states config list opts into drafts @@ -93,7 +98,7 @@ func ListsDraft(includeStates []string) bool { // state is admitted only when that filter admits it too. Unknown state names // are dropped, and a list with none left admits approved knowledge only. func AgentScope(layers, repos, types, tags, includeStates []string) TOCScope { - sc := TOCScope{Repos: repos, Types: types, Tags: tags} + sc := TOCScope{Repos: repos, Types: types, Tags: tags, HideAutoMemoryDrafts: true} for _, l := range layers { if l = strings.ToLower(strings.TrimSpace(l)); l != "" { sc.Layers = append(sc.Layers, LayerType(l)) @@ -161,7 +166,7 @@ var exclusionOrder = []string{ExcludedLifecycle, ExcludedLayer, ExcludedRepo, Ex // passes the scope, otherwise the reason code of the first failing check in // the order lifecycle, layer, repo, type, tag. func (sc TOCScope) ExclusionReason(f Fact) string { - if !lifecycleAllowed(f.EffectiveState(), sc.IncludeStates) { + if !lifecycleAllowed(f.EffectiveState(), sc.IncludeStates) || (sc.HideAutoMemoryDrafts && IsAutoMemoryDraft(f)) { return ExcludedLifecycle } if len(sc.Layers) > 0 && !containsLayer(sc.Layers, f.Layer) { diff --git a/src/pkg/scheduler/kick_priming_auto_memory_test.go b/src/pkg/scheduler/kick_priming_auto_memory_test.go new file mode 100644 index 0000000000..bbe6970977 --- /dev/null +++ b/src/pkg/scheduler/kick_priming_auto_memory_test.go @@ -0,0 +1,97 @@ +package scheduler + +import ( + "log/slog" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/knowledge" + "github.com/hivecommons/hive/pkg/knowledge/climemory" +) + +// TestPrimeKnowledge_AutoMemoryDraftsNeverPrimedUntilApproved is the #17058 +// acceptance test: a fact the CLI-memory drain wrote reaches no kick while it +// is a draft — not for an approved-only scope, not for a scope that admits +// drafts, not even when the primer config itself admits drafts — and the same +// fact is primed once an operator approves it through the lifecycle state API. +func TestPrimeKnowledge_AutoMemoryDraftsNeverPrimedUntilApproved(t *testing.T) { + memDir := filepath.Join(t.TempDir(), ".claude", "projects", "-data-agents-developer", "memory") + if err := os.MkdirAll(memDir, 0o755); err != nil { + t.Fatal(err) + } + const drained = "Webhook retry needs the idempotency key on every resend" + if err := os.WriteFile(filepath.Join(memDir, "MEMORY.md"), []byte("- "+drained+".\n"), 0o644); err != nil { + t.Fatal(err) + } + vaultDir := t.TempDir() + const approved = "Webhook retry approved fact" + if err := os.WriteFile(filepath.Join(vaultDir, "approved.md"), []byte("---\ntitle: "+approved+"\ntype: gotcha\nlayer: project\nstate: approved\n---\nRelevant to the webhook retry path.\n"), 0o644); err != nil { + t.Fatal(err) + } + + logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})) + api := knowledge.NewKnowledgeAPI(nil, knowledge.KnowledgeConfig{Enabled: true, Engine: "file"}, logger) + if err := api.ConnectVault(vaultDir, "bead-synth-wiki"); err != nil { + t.Fatal(err) + } + store := api.GetVaultStore(vaultDir) + drainer := &climemory.Drainer{Dir: vaultDir, Store: store, Layer: knowledge.LayerProject} + res := drainer.Drain(climemory.Request{Agent: "developer", Sources: []climemory.Source{{CLI: climemory.CLIClaude, Path: memDir}}}) + if res.Drained != 1 || len(res.Errors) != 0 { + t.Fatalf("drain = %+v, want one drafted fact", res) + } + files, err := filepath.Glob(filepath.Join(vaultDir, "cli-memory-*.md")) + if err != nil || len(files) != 1 { + t.Fatalf("drained entries = %v, %v; want one", files, err) + } + slug := strings.TrimSuffix(filepath.Base(files[0]), ".md") + if f, err := store.ReadPage(slug); err != nil || f.EffectiveState() != knowledge.StateDraft { + t.Fatalf("drained entry %s = %+v, %v; want a draft", slug, f, err) + } + + issues := []github.Issue{makeIssue("org/repo", 1, "Webhook retry fails", "", 5, []string{"webhook", "retry", "idempotency"}, false)} + newSched := func(primerStates []knowledge.LifecycleState) *Scheduler { + primer := knowledge.NewPrimer(nil, knowledge.PrimerConfig{MaxFacts: 25, IncludeStates: primerStates}, logger) + primer.AddFileStore("bead-synth-wiki", store, knowledge.LayerProject) + s := newScheduler() + s.cfg.Knowledge.AgentScopes = map[string]config.KnowledgeAgentScope{ + "quality": {Layers: []string{"project"}}, + "developer": {IncludeStates: []string{"draft"}}, + "architect": {IncludeStates: []string{"all"}}, + } + s.SetPrimer(primer) + return s + } + defaultPrimer := newSched(nil) + draftPrimer := newSched([]knowledge.LifecycleState{knowledge.StateDraft}) + agents := []string{"quality", "developer", "architect", "outreach"} + + for _, s := range []*Scheduler{defaultPrimer, draftPrimer} { + for _, agent := range agents { + got := s.primeKnowledge(agent, issues) + if !strings.Contains(got, approved) { + t.Fatalf("%s: approved control fact missing, the kick was not primed:\n%s", agent, got) + } + if strings.Contains(got, drained) { + t.Errorf("%s: auto-memory draft reached the kick:\n%s", agent, got) + } + } + } + + if _, err := api.SetEntryState(slug, knowledge.StateApproved, ""); err != nil { + t.Fatalf("approving %s through the state API: %v", slug, err) + } + for _, agent := range agents { + got := defaultPrimer.primeKnowledge(agent, issues) + if !strings.Contains(got, drained) { + t.Errorf("%s: approved auto-memory fact not primed:\n%s", agent, got) + } + if strings.Contains(got, "(draft)") { + t.Errorf("%s: approved auto-memory fact still rendered as a draft:\n%s", agent, got) + } + } +} From 039581cf3d89c9104937366024c58092c6138d02 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Sat, 7 Nov 2026 20:21:43 -0500 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20knowledge:=20fix=20legacy-dr?= =?UTF-8?q?ain=20test=20fixture=20path=20and=20settings-parity=20false=20p?= =?UTF-8?q?ositive?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review fixes for #17141: - TestKnowledgeDrainLegacyMemory: put the fixture under a .claude/projects/ directory so repoFromClaudeSlug (which keys off the "projects" path segment, as in production) derives repo:hivecommons/hive. - drain-legacy 409 message: stop spelling out the dotted hive.yaml key agents.cli_memory.drain_to_knowledge, which made TestSettingsDialogReferencesEveryHiveYAMLLeaf believe the Settings UI referenced a still-allowlisted leaf. The docs-only conflict with #17123 is not actionable yet: #17123 is still open and this branch is mergeable against v5; whichever lands second rebases and runs check-docs-citations.py --fix. Hive-Fix-Attempt: 1/6 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- src/pkg/dashboard/api_knowledge_cli_memory.go | 4 +++- src/pkg/dashboard/api_knowledge_cli_memory_test.go | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/src/pkg/dashboard/api_knowledge_cli_memory.go b/src/pkg/dashboard/api_knowledge_cli_memory.go index e802895c55..9fc565594b 100644 --- a/src/pkg/dashboard/api_knowledge_cli_memory.go +++ b/src/pkg/dashboard/api_knowledge_cli_memory.go @@ -38,7 +38,9 @@ func (s *Server) handleKnowledgeDrainLegacyMemory(w http.ResponseWriter, r *http } vault := s.deps.Knowledge.AutoMemoryVault() if vault == nil { - jsonError(w, "the bead-synth-wiki vault is not connected; configure bead stores or set agents.cli_memory.drain_to_knowledge so drained drafts land in a vault the primer reads", http.StatusConflict) + // Spelled without the dotted hive.yaml path so the settings-parity + // guard does not mistake this message for a Settings UI reference. + jsonError(w, "the bead-synth-wiki vault is not connected; configure bead stores or enable the CLI-memory drain (drain_to_knowledge under the agent's cli_memory block) so drained drafts land in a vault the primer reads", http.StatusConflict) return } sources, err := climemory.LegacyClaudeSources(legacyClaudeProjectsDir) diff --git a/src/pkg/dashboard/api_knowledge_cli_memory_test.go b/src/pkg/dashboard/api_knowledge_cli_memory_test.go index b10804f618..5878a3ffd7 100644 --- a/src/pkg/dashboard/api_knowledge_cli_memory_test.go +++ b/src/pkg/dashboard/api_knowledge_cli_memory_test.go @@ -95,7 +95,9 @@ func postLegacyDrain(s *Server, body string) (int, map[string]interface{}) { } func TestKnowledgeDrainLegacyMemory(t *testing.T) { - projects := t.TempDir() + // Mirror ~/.claude/projects//memory: repoFromClaudeSlug keys off + // the "projects" segment, so the fixture must carry it too. + projects := filepath.Join(t.TempDir(), ".claude", "projects") prev := legacyClaudeProjectsDir legacyClaudeProjectsDir = projects t.Cleanup(func() { legacyClaudeProjectsDir = prev })