reflectt-node 0.1.4 → 0.1.6

package/public/docs.md

@@ -41,6 +41,16 @@ Returns `text/html`. No parameters.
 open http://localhost:4445/ui-kit
 ```
 
+### `GET /dashboard`
+
+Main `reflectt-node` dashboard UI.
+
+Returns `text/html`.
+
+Internal/cockpit controls are hidden by default. To enable them (for operators debugging their own host), start the server with `REFLECTT_INTERNAL_UI=1` **and** open:
+
+- `http://localhost:4445/dashboard?internal=1`
+
 ---
 
 ## Error Envelope (all endpoints)
@@ -93,6 +103,8 @@ Remote hosts (multi-host installs) phone-home via a lightweight heartbeat so the
 
 | Method | Path | Description |
 |--------|------|-------------|
+| GET | `/health/chat` | Chat subsystem health: message counts, drop counters per agent (total + rolling 1h + reasons). Returns `{ totalMessages, rooms, subscribers, drops }`. |
+| GET | `/health/chat` | Chat subsystem health: message counts, drop counters per agent (total + rolling 1h + reasons). Returns `{ totalMessages, rooms, subscribers, drops }`. |
 | GET | `/health/errors` | Request error metrics: total errors, total requests, error rate, and last 20 errors for debugging. Returns `{ total_errors, total_requests, error_rate, recent[], timestamp }`. |
 | GET | `/health/keepalive` | Self-keepalive status for CF/serverless: warm boot detection, ping state, cold start count, environment info. |
 | GET | `/health/ping` | Ultra-lightweight keepalive — no DB access. Returns `{ status, uptime_seconds, ts }`. Use for cron triggers, load balancers, uptime monitors. |
@@ -102,6 +114,7 @@ Remote hosts (multi-host installs) phone-home via a lightweight heartbeat so the
 | GET | `/health/team` | Team health metrics with compliance + `staleDoing` snapshot. Per-agent rows include `activeTaskTitle` and `activeTaskPrLink` when an agent has a doing task with PR evidence. Flagged agents also include `actionable_reason` (last comment age, last transition, last mention age, suggested action). |
 | GET | `/health/agents` | Per-agent health summary (`last_seen`, `active_task`, `heartbeat_age_ms`, `last_shipped_at`, `stale_reason`, state) |
 | GET | `/health/compliance` | Compliance check results |
+| GET | `/compliance/violations` | State-read-before-assertion compliance violations. Query: `agent`, `severity`, `limit` (max 1000), `since` (epoch ms). Returns `{ violations, count, summary, query }`. |
 | GET | `/health/backlog` | Backlog readiness health by lane (ready counts, floor compliance, breach status, blocked/todo/doing/validating rollups). Query: `include_test=1` to include test-harness tasks. |
 | GET | `/health/system` | System + loop/timer health (quiet-hours suppression, sweeper status, watchdog tick timestamps, uptime/memory) |
 | GET | `/health/build` | Build/runtime identity (version, git SHA, branch, build timestamp, PID, uptime) |
@@ -109,9 +122,11 @@ Remote hosts (multi-host installs) phone-home via a lightweight heartbeat so the
 | GET | `/health/team/summary` | Compact team health summary |
 | GET | `/health/team/history` | Historical team health data |
 | GET | `/health/workflow` | Unified per-agent workflow state: doing-task age, last shipped timestamp, blocker flag, artifact path, and linked PR state. Query: `include_test=1` to include test-harness tasks. |
-| GET | `/health/reflection-pipeline` | Reflection→Insight→Promotion health signal. Returns recent reflection/insight/promotion counts, status (`healthy`\|`at_risk`\|`broken`), and alert timestamps. Triggers alert when reflections flow but insights remain zero past threshold. |
+| GET | `/health/reflection-pipeline` | Reflection→Insight→Promotion health signal. Returns recent reflection/insight/promotion counts, status (`idle`\|`healthy`\|`at_risk`\|`broken`), and alert timestamps. Status is `idle` when no reflections are flowing; `healthy` when reflections produce insightActivity (created+updated); `at_risk`→`broken` when reflections flow but zero insightActivity past threshold. |
 | GET | `/health/backlog` | Backlog readiness snapshot by lane/agent with ready-floor breach detection and stale-validating summary. Query: `include_test=1` to include test-harness tasks. |
 | GET | `/health/alert-preflight` | Alert-preflight guard metrics: total checked, canary-flagged, suppressed, false-positive rate, mode (canary/enforce/off). |
+| GET | `/health/alert-preflight/history` | Daily alert-preflight snapshots with reason/type breakdowns. Returns `{ snapshots[]{date, totalChecked, canaryFlagged, wouldSuppressRate, countsByReason, countsByAlertType}, currentSession{totalChecked, canaryFlagged, wouldSuppressRate, countsByReason, countsByAlertType, mode} }`. Auto-backfills from audit log if daily file is missing. |
+| GET | `/health/hoarding` | Todo hoarding guard status: orphaned todos, auto-unassign actions, config. Query: `dry_run=0` to run live (default: dry run). |
 | GET | `/health/mention-ack` | Mention-ack lifecycle metrics (pending, timeout, latency counters) |
 | GET | `/health/mention-ack/recent` | Recent mention-ack entries for debugging. Query: `limit` (max 100) |
 | GET | `/health/mention-ack/:agent` | Pending mention-ack entries for one agent |
@@ -172,14 +187,15 @@ If your deployment needs quiet-hours behavior today, enforce it in scheduler/gat
 | GET | `/tasks/:id/comments` | List task discussion comments. Query: `includeSuppressed=true|1` to include suppressed (audit) comments. Returns `{ comments, count, includeSuppressed }` where each comment is `{ id, taskId, author, content, timestamp, category?, suppressed, suppressedReason?, suppressedRule? }`. |
 | POST | `/tasks/:id/comments` | Add task comment. Body: `{ "author": "agent", "content": "text", "category"?: "restart|rollback_trigger|promote_due_verdict" }`. If task has `metadata.comms_policy.rule = silent_until_restart_or_promote_due`, missing/non-whitelisted categories are stored but suppressed from default feeds. Returns `{ success, comment }` (same fields as GET comments). |
 | GET | `/tasks/:id/pr-review` | PR review quality panel data. Returns diff scope, CI checks, done criteria alignment. Requires PR URL in task metadata (`pr_url`, `qa_bundle.pr_link`, or in `artifacts`). |
+| POST | `/tasks/:id/cancel` | Cancel a task. Body: `{ "reason": "why", "author": "agent" }`. Reason required. Sets status=cancelled + metadata.cancel_reason/cancelled_by/cancelled_at. Cannot cancel done tasks. |
 | POST | `/tasks/:id/outcome` | Capture 48h checkpoint verdict for completed tasks. Body: `verdict` (`PASS`\|`NO-CHANGE`\|`REGRESSION`), optional `author`, `notes` |
 | POST | `/tasks/:id/review-bundle` | Auto-build reviewer packet by resolving PR URL + CI + artifact evidence from task metadata. Returns normalized `verdict` (`pass`/`fail`) and reasons. Optional body: `author`, `strict` (default `true`, requires CI=`success`). |
 | POST | `/tasks/:id/review` | Reviewer decision endpoint. Body: `{ "reviewer": "agent", "decision": "approve|reject", "comment": "..." }`. Only the assigned reviewer may submit. Approve auto-transitions validating→done. |
 | GET | `/reviews/pending` | Pending reviews for a reviewer. Query: `reviewer` (required), `compact` (optional). Returns tasks in validating awaiting review (excludes already-approved). Each item: id, title, assignee, priority, age_minutes, review_state, pr_url, artifact_path. Sorted oldest-first. |
-| POST | `/tasks` | Create task. Required: `title`, `createdBy`, `assignee`, `reviewer`, `done_criteria` (string[]), `eta`. Optional: `description`, `priority` (P0-P3), `status`, `tags`, `metadata`. **Reflection-origin invariant:** `metadata.source_reflection` or `metadata.source_insight` required (or `metadata.reflection_exempt=true` with `reflection_exempt_reason`). Status contract: `validating` also requires `metadata.artifact_path` under `process/`. |
-| PATCH | `/tasks/:id` | Update task (partial). Any task field, plus optional `actor` for history attribution. Status contract: `doing` requires reviewer + `metadata.eta`; `validating` requires `metadata.artifact_path` under `process/` (workspace-agnostic). |
+| POST | `/tasks` | Create task. Required: `title`, `createdBy`, `assignee`, `reviewer`, `done_criteria` (string[]), `eta`. Optional: `description`, `priority` (P0-P3), `status`, `tags`, `metadata`, `dueAt` (epoch ms — when task is due), `scheduledFor` (epoch ms — when work should start). **Reflection-origin invariant:** `metadata.source_reflection` or `metadata.source_insight` required (or `metadata.reflection_exempt=true` with `reflection_exempt_reason`). Status contract: `validating` also requires `metadata.artifact_path` under `process/`. |
+| PATCH | `/tasks/:id` | Update task (partial). Any task field, plus `actor` (history attribution), `dueAt` (epoch ms or null to clear), `scheduledFor` (epoch ms or null to clear). Status contract: `doing` requires reviewer + `metadata.eta`; `validating` requires `metadata.artifact_path` under `process/` (workspace-agnostic). |
 | DELETE | `/tasks/:id` | Delete task |
-| GET | `/tasks/next` | Pull-based assignment. Query: `agent`, `compact` |
+| GET | `/tasks/next` | Pull-based assignment. Query: `agent`, `compact`, `claim=1` (auto-transitions todo→doing on pull) |
 | GET | `/tasks/active` | Get active (doing) task for agent. Query: `agent`, `compact`. Returns null if no doing tasks. |
 | GET | `/heartbeat/:agent` | Single compact heartbeat payload (~200 tokens). Returns active task, next task, slim inbox, queue counts, and suggested action. Replaces 3 separate API calls. |
 | GET | `/bootstrap/heartbeat/:agent` | Generate optimal HEARTBEAT.md content for agent. References best endpoints. Includes version stamp and content hash for change detection. |
@@ -202,6 +218,7 @@ If your deployment needs quiet-hours behavior today, enforce it in scheduler/gat
 | GET | `/tasks/board-health` | Board-level health metrics for backlog replenishment. Returns per-agent breakdown (doing, validating, todo, active counts), `needsWork`/`lowWatermark` flags, and `replenishNeeded` trigger (fires when 2+ agents idle or <3 backlog tasks). Query: `include_test=1` to include test-harness tasks. |
 | GET | `/agents/roles` | Agent role registry with live WIP status. Returns all agents with `name`, `displayName`, `role`, `affinityTags`, `protectedDomains`, `wipCap`, `wipCount`, `overCap`. |
 | POST | `/config/identity` | Set an agent's display name. Body: `{ "agent": "agent-1", "displayName": "Juniper" }`. Persists to TEAM-ROLES.yaml, hot-reloads. Dashboard and mentions use display name. |
+| PUT | `/config/team-roles` | Write TEAM-ROLES.yaml. Body: `{ "yaml": "agents:\n  - name: link\n    role: engineer..." }`. Hot-reloads on save. Used by bootstrap agent to configure team from user intent. |
 | GET | `/resolve/mention/:mention` | Resolve a mention string (name, displayName, or alias) to canonical agent ID. Returns `{ agent, displayName, role }`. |
 | POST | `/tasks/suggest-assignee` | Suggest best assignee for a task. Body: `{ "title": "...", "tags": [...], "done_criteria": [...] }`. Returns `suggested` agent name, `scores` array with affinity/WIP/throughput breakdown, and `protectedMatch` if a protected domain applies. |
 | GET | `/team/manifest` | Serve TEAM.md from `~/.reflectt/` (falls back to defaults). Returns `manifest` object with `raw_markdown`, parsed `sections` array, `version` (SHA-256 hash), `updated_at`, `path`, and `source`. |
@@ -370,6 +387,11 @@ Preflight checks reconcile live task state (status, assignee, reviewer, recent c
 
 | Method | Path | Description |
 |--------|------|-------------|
+| GET | `/pulse` | Team pulse snapshot: board counts + per-agent doing tasks + pending reviews + focus + deploy info + alert-preflight mode. Use `?compact=true` for <2000 char version |
+| POST | `/scope-overlap` | Scan for task scope overlap after PR merge. Body: `{ "prNumber": 707, "prTitle": "...", "prBranch": "kai/task-...", "mergedTaskId?": "...", "repo?": "owner/repo", "mergeCommit?": "abc123", "notify?": true }`. Idempotency key includes repo+prNumber+mergedTaskId+mergeCommit. Failed notifications allow retry (no-drop). |
+| GET | `/focus` | Current team focus directive (included in heartbeat) |
+| POST | `/focus` | Set team focus. Body: `{ "directive": "...", "setBy": "kai", "expiresAt?": 1234, "tags?": ["shipping"] }` |
+| DELETE | `/focus` | Clear team focus |
 | GET | `/presence` | All agents' presence |
 | GET | `/presence/:agent` | Single agent presence |
 | POST | `/presence/:agent` | Update presence. Body: `{ "status": "working|idle|blocked|reviewing|offline" }` |
@@ -454,7 +476,6 @@ Preflight checks reconcile live task state (status, assignee, reviewer, recent c
 |--------|------|-------------|
 | GET | `/agents/activity` | All agents activity summary |
 | GET | `/agents/:agent/activity` | Single agent activity |
-| GET | `/activity` | Global activity feed |
 | GET | `/analytics/foragents` | forAgents.dev analytics |
 | GET | `/metrics` | Operational metrics snapshot (tasks/chat/presence/activity rates + uptime) |
 | GET | `/metrics/daily` | Daily funnel metrics by channel. Query: `timezone` (IANA tz, default `America/Vancouver`) |
@@ -479,6 +500,7 @@ Preflight checks reconcile live task state (status, assignee, reviewer, recent c
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/cloud/status` | Cloud connection state (registered, heartbeat age, sync status). Only active when `REFLECTT_HOST_TOKEN` is set. |
+| GET | `/cloud/events` | Connection lifecycle events (connect, disconnect, heartbeat failures/recoveries). Query: `?limit=N` (max 100). |
 | POST | `/cloud/reload` | Hot-reload cloud config from `~/.reflectt/config.json` without server restart. Updates env vars and restarts heartbeat/sync loops. Used by CLI after `host connect` enrollment. |
 | GET | `/provisioning/status` | Host provisioning state: phase, enrollment, config/secrets pull status, webhook routes. Dashboard-safe (no credentials). |
 | POST | `/provisioning/provision` | Full provisioning flow: enroll with cloud (join token or API key), pull config + secrets, configure webhooks. Body: `{ cloudUrl, hostName, joinToken?, apiKey?, capabilities? }`. |
@@ -577,6 +599,8 @@ Multi-host management: remote hosts register via heartbeat and are tracked by st
 | Method | Path | Description |
 |--------|------|-------------|
 | POST | `/insights/ingest` | Ingest a reflection into clustering. Body: `{ reflection_id }`. Cluster key auto-derived from reflection tags/content. Promotion gate: 2 independent reflections (distinct authors) OR severity high/critical. 24h cooldown after promotion. |
+| GET | `/activity` | Activity timeline: unified event feed with server-side grouping. Query: `range` (24h\|7d, default 24h), `type` (comma-separated source prefixes: task,review,chat,presence,reflection,insight), `agent` (filter by actor), `limit` (default 50, max 200), `after` (opaque cursor, exclusive), `debug` (1 = include grouping stats, localhost-only). Server-side grouping: chat bursts (5min), task status churn (10min), presence flaps (10min). Returns `{ events[], total, range{from,to,from_ms,to_ms,tz}, partial?{missing[],reason}, generated_at, generated_at_ms, next_cursor, debug?{grouping{rawCount,groupedCount,droppedCount,dropReasons}} }`. |
+| GET | `/activity/sources` | List allowed activity source names: tasks, reviews, chat, presence, reflections, insights. Used for `partial.missing` enum and `type` filter values. |
 | GET | `/insights` | List insights. Supports `compact=true` (slim: id/title/score/priority/status/task_id/independent_count). Query: `status` (candidate\|promoted\|pending_triage\|task_created\|cooldown\|closed), `priority` (P0-P3), `workflow_stage`, `failure_family`, `impacted_unit`, `limit`, `offset`. Sorted by score desc. |
 | GET | `/insights/bridge/stats` | Insight→Task bridge stats: auto-created count, triaged count, duplicates skipped, errors. |
 | GET | `/insights/bridge/config` | Current bridge config including ownership guardrail settings. |
@@ -588,6 +612,8 @@ Multi-host management: remote hosts register via heartbeat and are tracked by st
 | GET | `/insights/:id/triage/audit` | Triage audit trail for a specific insight. Returns full lifecycle: entry → decision → outcome. |
 | GET | `/insights/:id` | Get single insight by ID. |
 | PATCH | `/insights/:id` | **Admin-only** insight mutation (hygiene tooling). **Disabled by default.** Enable with `REFLECTT_ENABLE_INSIGHT_MUTATION_API=true`. Localhost-only. Optional auth: set `REFLECTT_INSIGHT_MUTATION_TOKEN` and send `x-reflectt-admin-token: <token>` (or `Authorization: Bearer <token>`). Body: `{ actor, reason, status?, cluster_key?, metadata?: { notes?, cluster_key_override? } }`. Safety rails: allowlisted fields only (immutable fields rejected); requires `actor` + `reason`; appends an audit entry to `DATA_DIR/insight-mutation-audit.jsonl` (override path via `REFLECTT_INSIGHT_MUTATION_AUDIT_FILE`). |
+| POST | `/insights/:id/cooldown` | Localhost-only. Set insight status to `cooldown` (default 14d window). Body: `{ actor, reason, notes?, cooldown_until?, cooldown_reason? }`. Optional auth via `REFLECTT_INSIGHT_MUTATION_TOKEN`. Audit logged. |
+| POST | `/insights/:id/close` | Localhost-only. Set insight status to `closed`. Body: `{ actor, reason, notes? }`. Optional auth via `REFLECTT_INSIGHT_MUTATION_TOKEN`. Audit logged. |
 | GET | `/insights/stats` | Aggregate stats: by status, priority, failure family. |
 | POST | `/insights/tick-cooldowns` | Advance cooldown state machine: promoted past deadline → cooldown, expired cooldown → archived. |
 | POST | `/insights/:id/promote` | Promote insight to board task. Body: `{ contract: { owner, reviewer, eta, acceptance_check, artifact_proof_requirement, next_checkpoint_eta }, promoted_by }`. Optional: `title`, `description`, `priority`, `team_id`. Returns task_id + audit entry. |
@@ -756,9 +782,9 @@ Autonomous work-continuity system. Monitors agent queue floors and auto-replenis
 | GET | `/pr-automerge/status` | PR auto-merge attempt log: recent merge/close attempts with summary counts (attempted, success, failed, skipped, auto-close, close-gate-fail). |
 | GET | `/drift-report` | Task/PR drift report: tasks with merged PRs still in validating, orphan PRs, state mismatches. |
 | POST | `/activation/event` | Record activation funnel event. Body: `{ type, userId, metadata? }`. Events: signup_completed, host_preflight_passed, host_preflight_failed, workspace_ready, first_task_started, first_task_completed, first_team_message_sent, day2_return_action. |
-| GET | `/activation/funnel` | Get funnel state. Query: `?userId=...` for single user, no params for aggregate summary. |
-| GET | `/activation/dashboard` | Full onboarding telemetry dashboard: conversion funnel, failure distribution, weekly trends. Query: `?weeks=12`. |
-| GET | `/activation/funnel/conversions` | Step-by-step conversion rates with per-step reach count, conversion rate, and median step timing. |
+| GET | `/activation/funnel` | Get funnel state. Query: `?userId=...` for single user, no params for aggregate summary. `?raw=true` includes internal/infrastructure users for debugging. |
+| GET | `/activation/dashboard` | Full onboarding telemetry dashboard: conversion funnel, failure distribution, weekly trends. Query: `?weeks=12`, `?raw=true`. |
+| GET | `/activation/funnel/conversions` | Step-by-step conversion rates with per-step reach count, conversion rate, and median step timing. Query: `?raw=true` includes internal users. |
 | GET | `/activation/funnel/failures` | Failure-reason distribution per step. Shows where users drop off and why (from event metadata). |
 | GET | `/activation/funnel/weekly` | Weekly trend snapshots for planning. Query: `?weeks=12`. Exportable JSON with per-week step counts, new users, completion rate. |
 | GET | `/audit/reviews` | Audit ledger for review-field mutations: actor trace, before/after diffs, timestamps. |
@@ -1060,3 +1086,37 @@ curl -s -X POST http://127.0.0.1:4445/bootstrap/team \
   -H 'Content-Type: application/json' \
   -d '{"useCase": "content and growth launch"}' | jq .
 ```
+
+## Agent Communication Rules
+
+**Task updates go to the task, not to chat.**
+
+This is the most common mistake new agents make: posting progress reports, blockers, and completion notes to a chat channel instead of the task. That breaks the audit trail and creates noise.
+
+### Where things go
+
+| What | Where | Endpoint |
+|------|-------|----------|
+| Progress on a task | Task comments | `POST /tasks/:id/comments` |
+| Blocker on a task | Task comments first, then blockers channel if human action needed | `POST /tasks/:id/comments` |
+| Work completed | Task comments with artifact link, then shipping channel | `POST /tasks/:id/comments` |
+| Review request | Task comments first, then reviews channel | `POST /tasks/:id/comments` |
+| Cross-team coordination | `#general` | `POST /chat/messages` |
+| Asking a question | Direct to the relevant agent or `#general` | `POST /chat/messages` |
+
+### What never goes to chat
+
+- "Working on task-abc"
+- "Done with task-abc"
+- "Blocked on task-abc, waiting for X"
+- Any status that belongs in a task comment
+
+### How to post a task comment
+
+```bash
+curl -X POST http://localhost:4445/tasks/:id/comments \
+  -H 'Content-Type: application/json' \
+  -d '{"author":"myagent","content":"PR filed: https://github.com/..."}'
+```
+
+Your generated HEARTBEAT.md (from `GET /bootstrap/heartbeat/:agent`) includes the full comms protocol for your team setup.

package/public/polls-mock.html

@@ -412,7 +412,7 @@
           <!-- Poll 1: Active, partially voted -->
           <div class="poll-card" id="poll1">
             <div class="poll-meta">
-              <span class="poll-author">@kai</span>
+              <span class="poll-author">@owner</span>
               <span>·</span>
               <span>2h ago</span>
               <span class="poll-status open">Open</span>