Commit graph

78 commits

Author SHA1 Message Date
Brad Groux
44b63455ea fix(docker): standardize path resolution across all services (#102)
Created shared paths.ts utility as single source of truth for all path
resolution. Refactored 7 services to use it:

- server/src/utils/paths.ts: New shared utility with JSDoc docs
- task-service: Uses getTasksActiveDir()/getTasksArchiveDir()
- activity-service: Uses getDataDir()
- chat-service: Uses getChatsDir()
- audit-service: Uses getAuditDir()
- metrics/helpers: Uses getProjectRoot()/getTelemetryDir()
- backlog-repository: Uses getTasksBacklogDir()

Resolution priority: DATA_DIR/VERITAS_DATA_DIR env var > auto-discovery
of monorepo root (walks up looking for pnpm-workspace.yaml) > cwd fallback.
Filesystem root guard prevents silent '/' resolution (the original EACCES bug).

Backwards compatible: existing DATA_DIR configurations unchanged.
Cross-model reviewed: 10/10/10/10 (GPT-5.1 authored, Claude Sonnet 4.5 reviewed).

Closes #102

[author: gpt-5.1]
[reviewed-by: claude-sonnet-4.5]
Version: 2.1.3
2026-02-07 22:02:05 -06:00
Brad Groux
6aaffc883c docs: update roadmap + fix version reference in CLI guide
- README.md: Added v2.2 planned, v2.1.2 shipped, v2.1.1 shipped sections to roadmap
- CLI-GUIDE.md: Updated deployment example version from 2.1.0 to 2.1.2

Reviewed: 10/10/10/10 (docs only)
2026-02-07 17:04:22 -06:00
Brad Groux
d9b946b215 chore: bump version to 2.1.2 — Docker path resolution fix
- Version bumped in all package.json files (root, server, web, shared)
- CHANGELOG: v2.1.2 entry documenting WORKDIR fix and root cause
- README: version badge updated to 2.1.2
- DEPLOYMENT.md: path resolution note added
- TROUBLESHOOTING.md: EACCES fix guide added
- docker-compose.yml: WORKDIR comment added

Reviewed: 10/10/10/10
Related: #102
2026-02-07 16:57:37 -06:00
Brad Groux
bcd212dac4 docs: update changelog, readme, and guides for v2.1.1 release 2026-02-07 15:01:32 -06:00
Brad Groux
e0bd0102cb fix: add TRUST_PROXY env var for reverse proxy deployments (#100)
Resolves #100. Adds configurable trust proxy setting via TRUST_PROXY
environment variable. Supports numeric hop counts, subnet strings, and
named values (loopback, linklocal, uniquelocal). TRUST_PROXY=true is
intentionally blocked (unsafe for production — logs warning and falls
back to default). Disabled by default (no behavior change).

Includes documentation updates for nginx, Caddy, and Docker deployments.
2026-02-07 14:53:02 -06:00
Brad Groux
8cce9f24c4 feat: Squad chat protocol scripts, system events, model attribution
- Add squad-post.sh for regular agent messages
- Add squad-event.sh for lifecycle events (spawned/completed/failed/status)
- Add model field to squad messages (types, server, UI, scripts)
- System events render as divider lines in squad chat panel
- Model attribution displays next to agent names in UI
- Full protocol documented in SQUAD-CHAT-PROTOCOL.md
- Updated CONTRIBUTING.md, README.md, and all SOPs
- Added VK_HOST/VK_PORT env vars to .env.example

4-check cross-model review: 10/10 (Code/GPT-5.1, Func/Grok, Perf/Grok, Sec/GPT-5.1)
Agents: R2-D2 (feature), TARS/CASE/Ava/K-2SO (reviews)
2026-02-07 13:04:17 -06:00
Brad Groux
e79b7c3f5b v2.1.0: Documentation, security hardening, performance optimizations
Documentation:
- Updated README with all new features (squad chat, broadcasts, deliverables, polling, delegation, OpenClaw integration)
- Added Pre-Commit Review Protocol to CONTRIBUTING.md (mandatory 4 checks: code, functionality, performance, security)
- Added One Agent Per File development rule
- Created 5 comprehensive feature docs (docs/features/)
- Consolidated and cleaned up 8 scattered implementation docs
- Updated lessons learned with 6 additional insights from today

Security:
- Stripped gateway token from all API responses (write-only field)
- Added file locking to notification-service and config-service

Performance:
- Removed double cache invalidation in squad chat
- Added React.memo to message bubble components

Version bump: 2.0.0 → 2.1.0

All reviews passed 10/10 (code, functionality, performance, security)
Contributors: TARS, CASE, Ava, K-2SO, R2-D2, VERITAS
2026-02-07 11:51:24 -06:00
Brad Groux
a249dee1fb Merge: Squad chat, webhooks, delegation, polling + critical security fixes
Feature branches merged:
- Agent squad chat with real-time WebSocket updates
- Broadcast notifications (priority levels, read receipts)
- Task deliverables as first-class objects
- Efficient polling endpoint with change tracking
- Approval delegation / vacation mode

Security & stability fixes:
- Fix: path traversal vulnerability in broadcast storage
- Fix: TOCTTOU race condition in broadcast.markRead()
- Fix: double cache invalidation in squad chat
- Fix: file locking consistency for concurrent writes
- Add: default agent display name handling

Improvements:
- React.memo for message bubbles (perf)
- Save-on-blur for display name input
- Auto-scroll to latest in squad chat
- OpenClaw gateway wake integration
- One-agent-per-file development rule (CONTRIBUTING.md)

All reviews passed (code, functionality, performance, security)
27 files changed, comprehensive test coverage added

v2.0.0 ready for production
2026-02-07 11:30:52 -06:00
Brad Groux
8cfe28326d docs: comprehensive v2.0.0 documentation update
- FEATURES.md: Added Multi-Agent System section (registry, dashboard,
  assignment, mentions, permissions, error learning, doc freshness)
- FEATURES.md: Added Dashboard Widgets section (activity clock, hourly
  activity, where time went, wall time, session metrics, widget toggles,
  lifecycle hooks, cost prediction, timezone-aware metrics)
- FEATURES.md: Added v2.0 API endpoints to route table
- FEATURES.md: Updated response envelope with timezone meta fields
- CHANGELOG.md: Added #92 Dashboard Widget Toggles to v2.0.0
- README.md: Moved #92 from backlog to shipped in v2.0.0
- README.md: Cleaned stale 'NEW — v1.x' tags from pre-v2.0 features
- CLAUDE.md: Updated to v2.0.0 — added mcp/ package, multi-agent
  lessons, registry/telemetry file locations
- security.md: Added v2.0.0 changelog entry (permissions, MCP patch)
- All docs verified: no broken links, no stale version refs, no secrets
2026-02-05 20:54:37 -06:00
Brad Groux
69cf3c334c chore: v2.0.0 release prep
Version:
- Bump all packages to 2.0.0 (root, server, web, shared, mcp)

Security:
- Patch MCP SDK from ^1.25.3 to ^1.26.0 (GHSA-345p-7cg4-v4c7)
- Add rate limiting warning to README security section

Documentation:
- CHANGELOG: comprehensive v2.0.0 entry (18 features, fixes, credits)
- README: updated roadmap with v2.0 shipped features
- README: added v2.0 feature highlights (multi-agent, dashboard, lifecycle)
- README: version badge updated to 2.0.0
- AGENT-REGISTRY.md: VERITAS naming consistency (all caps)

Maintenance:
- Cleaned 21 stale feature branches (down to main only)
- Dashboard widget toggles scaffolding (#92)
- Pre-commit secret scan: clean
2026-02-05 20:45:36 -06:00
Brad Groux
c7ade9d32c VERITAS — all caps (it's an acronym) 2026-02-05 20:20:10 -06:00
Brad Groux
7c272963f5 docs: comprehensive Agent Registry documentation
- Full API reference (register, heartbeat, list, stats, capabilities, deregister)
- Agent lifecycle diagram (online → busy → idle → offline)
- Current 10-agent roster with roles, models, capabilities
- Sub-agent spawn template with registration block
- Name assignment order (TARS through Marvin)
- Dashboard integration notes
- Configuration reference
- File format spec
- Troubleshooting guide
2026-02-05 20:04:54 -06:00
Brad Groux
ec364c1695 docs: add documentation freshness guide with steward workflow (closes #74)
Inspired by Monika Voutov's BoardKit Orchestrator — 'stale docs = hallucinating AI'

- Doc update checklist for every task completion
- Freshness headers format: date | version | updater
- Three-phase automation plan: manual → hook-based → AI doc steward
- Repo rules (CLAUDE.md equivalent) for agents
- Trigger matrix: when to update what
- Credit: @mvoutov
2026-02-05 18:30:24 -06:00
Brad Groux
c57e368a25 docs: add mandatory telemetry emission steps to agent docs
The dashboard's Success Rate, Token Usage, and Average Run Duration
graphs are powered by run.* telemetry events that agents must emit
manually — they are NOT auto-captured like task.* events.

This has broken multiple times when agents lost their AGENTS.md
instructions. Now documented in:
- AGENTS-TEMPLATE.md (copy-paste for new agents)
- SOP-agent-task-workflow.md (full API flow with telemetry steps)

Both docs now include the exact curl commands for run.started,
run.completed, and run.tokens events, plus a table clarifying
what's auto-captured vs. manual.
2026-02-05 18:26:34 -06:00
Brad Groux
76c40f2d67 docs: add multi-agent git workflow guide — lessons from v2.0 sprint
- Branch collision problem and real-world example
- Three solutions: sequential, git worktree, orchestrator pattern
- Sub-agent task template with git rules
- Pre-commit hook handling for multi-agent
- Secret scanning SOP
- Orchestrator checklist
2026-02-05 18:04:51 -06:00
Brad Groux
fcf1756b79 feat: add agent self-reporting protocol with registry, heartbeat, and discovery (closes #52)
- Agent Registry Service: registration, heartbeat, capability discovery, stale detection
- REST API: POST /register, POST /:id/heartbeat, DELETE /:id, GET /stats, GET /capabilities/:cap
- Persistent storage: .veritas-kanban/agent-registry.json
- Auto-offline: agents without heartbeat for 5min marked offline
- AGENTS.md template: docs/AGENTS-TEMPLATE.md with full integration guide
2026-02-05 17:56:04 -06:00
Brad Groux
931d437b67 chore: Release v1.6.0
## Highlights
- Activity Page Redesign — Full-width status history, clickable navigation, color-coded badges
- Task Templates UI (#39) — Full management interface for templates
- Analytics API (#43) — Timeline and aggregate metrics endpoints
- Status Transition Hooks — Quality gates for task status changes
- 7 GitHub Issues Closed (#47, #48, #49, #51, #53, #56, #82)

## Changes
- Bump all packages to 1.6.0
- Update CHANGELOG.md with comprehensive release notes
- Update README.md version badge and roadmap
- Update FEATURES.md with new sections:
  - Task Templates (v1.6.0)
  - Analytics API (v1.6.0)
  - Dashboard Filter Bar (v1.6.0)
  - Redesigned Activity Feed section
- Activity page: purple for sub-agent, amber for in-progress, blue for done
- Status badges: uniform width, color-coded by status type
2026-02-04 22:11:13 -06:00
Brad Groux
51bd4da251 docs(#43): Add Analytics API documentation and Swagger schemas
- Add comprehensive ANALYTICS.md documenting all endpoints
- Document data models, metrics, and usage examples
- Add TESTING_ANALYTICS.md with test scenarios
- Update swagger.ts with analytics schemas and endpoints
- Include performance benchmarks and troubleshooting guide
2026-02-04 20:40:49 -06:00
Brad Groux
64998b0757 feat: Multiple bug fixes and enhancements
- fix(REL-001): Add withFileLock to 5 unguarded services
- fix(REL-002): Replace plain objects with useRef in useFeatureSettings
- fix(REL-003): Only clear dirty state on mutation success in useDebouncedSave
- fix(REL-004): Fix ActivityFeed knownIdsRef stale reference
- fix(REL-005): Fix ArchiveSidebar useMemo used as useEffect
- fix(REL-006): Fix ConflictResolver render-time setState
- fix(REL-007): Fix useSortableList stale rollback + array mutation
- feat(A11Y-001): Add aria-labels to icon-only buttons
- feat(A11Y-002): Add keyboard support to clickable divs
- feat(#41): Lessons Learned Field - UI component + API endpoint

Co-authored-by: Veritas <veritas@digitalmeld.io>
2026-02-04 20:37:18 -06:00
Brad Groux
f176592259 feat(US-1611): Complete orchestrator-inspired features
- #73 Prompts registry: prompt-registry/ with 10 starter templates ✓
- #74 Doc freshness: CLAUDE.md template + SOP-documentation-freshness.md ✓
- #75 Setup wizard: vk setup command ✓
- #76 Lifecycle hooks: hook-service.ts + SOP-lifecycle-hooks.md ✓
- #77 Shared resources: SOP-shared-resources.md ✓

Credit: Inspired by Monika Voutov's BoardKit Orchestrator
https://github.com/BoardKit/orchestrator

Closes #73, closes #74, closes #75, closes #76, closes #77
2026-02-04 09:47:38 -06:00
Brad Groux
4a1cf7d36d docs: US-1611 SOP-shared-resources — multi-repo resource sharing patterns
Added docs/SOP-shared-resources.md covering:
- Single repo vs multi-repo directory structures
- Mounting strategies (copy, symlinks, git submodules, npm packages)
- What to share vs what to keep project-specific
- Referencing shared resources in tasks and prompts
- Versioning and update protocols
- Migration checklist

Updated GETTING-STARTED.md to reference the new prompt-registry templates.

Credit: BoardKit Orchestrator (Monika Voutov) for the shared resources pattern.

Closes #77
2026-02-04 09:36:02 -06:00
Brad Groux
43c01ec8e8 feat: US-1611 prompt-registry — 10 copy/paste prompt templates
Created prompt-registry/ folder with starter templates:
- sprint-planning.md — Break epics into sprints
- worker-handoff.md — PM → Worker assignment
- cross-model-review.md — Claude ↔ GPT review gate
- feature-development.md — E2E feature implementation
- bug-triage.md — Investigation and fix workflow
- research-report.md — Deep research deliverable
- task-completion.md — Pre-completion checklist
- blocked-escalation.md — Blocker reporting
- pm-orchestration.md — PM agent managing workers
- standup-summary.md — Daily status report

Updated docs to reference prompt-registry/ instead of shared/prompt-registry/.

Credit: BoardKit Orchestrator (Monika Voutov) for the registry pattern.

Closes #69
2026-02-04 09:34:36 -06:00
Brad Groux
bf04c95421 docs: update CHANGELOG, README, TIPS-AND-TRICKS for v1.5.0 features
- CHANGELOG.md: Added CLI section for vk setup, Fixed section for archive/metrics/backlog bugs, Security section for SEC-001 extensions
- README.md: Added Setup & Onboarding section with vk setup examples
- TIPS-AND-TRICKS.md: Added vk setup to CLI shortcuts table
- GETTING-STARTED.md: Updated to reference vk setup as available (not roadmap)
2026-02-04 09:29:44 -06:00
Brad Groux
89d6efbe6e feat(cli): US-1611 vk setup — guided onboarding wizard
New CLI command that validates environment and helps new users get started:

- Checks Node version (requires >=18)
- Verifies server is running and accessible
- Tests API authentication
- Optionally creates a welcome task with next steps
- Supports --json output for automation
- Supports --skip-task to skip sample task creation

Updated docs/GETTING-STARTED.md to reference the new command.

Credit: BoardKit Orchestrator (Monika Voutov) for the wizard pattern inspiration.

Closes #71
2026-02-04 09:14:01 -06:00
Brad Groux
eeb11ba219 feat(US-1600): Complete SOP Sprint + fix GH-86 & GH-87
Documentation (8 new files in docs/):
- GETTING-STARTED.md: 5-min quickstart, BoardKit insights, sanity checks
- SOP-agent-task-workflow.md: Full lifecycle (claim → work → complete)
- SOP-sprint-planning.md: Epic → sprint → task hierarchy + estimation
- SOP-multi-agent-orchestration.md: PM + worker roles, handoff patterns
- SOP-cross-model-code-review.md: Claude ↔ GPT gate, checklist, RF-002 ref
- BEST-PRACTICES.md: 10 DOs + 10 DON'Ts based on real usage
- EXAMPLES-agent-workflows.md: 6 copy/pasteable recipes (feature, bug fix, docs, audit, content, research)
- TIPS-AND-TRICKS.md: CLI shortcuts, keyboard shortcuts, integrations (MCP, git worktrees, Obsidian)
- README.md: Added 'Documentation Map' linking all new docs

Bug Fixes:
- fix(GH-86): BulkActionsBar now handles archive errors gracefully
  * Per-task error tracking (replaces Promise.all)
  * Toast notifications on success/partial/failure
  * Logs individual failures to console

- fix(GH-87): Sidebar metrics now stay in sync with board state
  * Invalidate metrics cache when task status changes
  * Prevents up-to-30s lag in sidebar counts
  * Preserves timer state during mutations

Scripts:
- scripts/dev-clean.sh: Added explicit pnpm path resolution for launchd
- scripts/dev-watchdog.sh: Fixed restart storm prevention + pnpm path

BREAKING: None
TESTING:
- Manual: Bulk archive Done column tasks, verify toasts appear
- Manual: Move tasks between columns, verify sidebar counts update <2s
- Unit: Consider regression tests for metrics invalidation
2026-02-04 08:18:01 -06:00
Brad Groux
2192ca6beb docs: note planning is not a status (agent-facing) 2026-02-04 00:35:50 -06:00
Brad Groux
d98c8c6615 Dev reliability: add /api/health, dev:clean, and dev watchdog 2026-02-03 23:41:10 -06:00
Brad Groux
855dbfc850 Revert "Dev reliability: add /api/health, dev:clean, and dev watchdog"
This reverts commit a1c19d5772.
2026-02-03 23:40:53 -06:00
Brad Groux
a1c19d5772 Dev reliability: add /api/health, dev:clean, and dev watchdog 2026-02-03 23:37:15 -06:00
Brad Groux
872e01a50f chore: add landing page to docs/ for GitHub Pages + configure Pages from /docs 2026-02-01 02:55:26 -06:00
Brad Groux
b19a275ad0 docs: comprehensive v1.4 CLI workflow documentation — README, FEATURES, CHANGELOG, new CLI-GUIDE.md (#44) 2026-02-01 02:24:34 -06:00
Brad Groux
9369ca8bcf docs: update all documentation for v1.2.0 + v1.3.0
- Bump all package versions to 1.3.0
- README: version badge, blocked column, new feature highlights
- CHANGELOG: full v1.2.0 and v1.3.0 entries
- FEATURES.md: GitHub sync, activity feed, standup summary sections
- FEATURES.md: storage architecture, API envelope docs, new CLI commands
- FEATURES.md: updated API endpoints table and response format docs
2026-01-31 23:33:37 -06:00
Brad Groux
287ac80b3f fix: exempt localhost from auth rate limit (fixes #25) 2026-01-30 23:18:38 -06:00
Brad Groux
b536e60816 docs: add TROUBLESHOOTING.md with common issues and solutions 2026-01-30 23:11:36 -06:00
Brad Groux
793192e6b3 docs: rename Moltbot references to OpenClaw (formerly Clawdbot/Moltbot) 2026-01-29 23:39:11 -06:00
Brad Groux
c250a5a60f docs: final documentation pass for public release
- CONTRIBUTING: fix Node.js prerequisite (20 → 22), fix .env path, add seed docs, expand project structure
- CHANGELOG: move 1.1.0 to Unreleased (matches package.json 1.0.0), add seed data entry, fix link refs
- README: add examples/ and gitignored annotations to architecture tree
- docs/security.md: update Clawdbot reference to Moltbot, fix release date
2026-01-29 15:51:41 -06:00
Brad Groux
316126db24 docs: add screenshots and demo GIFs to README and FEATURES 2026-01-29 15:32:29 -06:00
Brad Groux
76b93ebe85 docs: update documentation for agent CRUD, theme toggle, and bug fixes 2026-01-29 07:23:26 -06:00
Brad Groux
c95500507e docs: clean up docs folder, update test counts
- Removed 13 sprint files (internal dev history)
- Removed 4 dated audit files + settings-architecture.md (internal working docs)
- Kept: DEPLOYMENT.md, FEATURES.md, security.md
- Updated FEATURES.md: 61 test files, 1,143 tests (was 51 files)
- Updated CHANGELOG.md: corrected test counts for v1.0.0
2026-01-29 06:02:18 -06:00
Brad Groux
f63f725fbb docs: update all repo links to BradGroux (primary repo) 2026-01-29 03:34:43 -06:00
Brad Groux
9cc08e9f4b docs: add comprehensive feature reference (docs/FEATURES.md) 2026-01-29 03:01:06 -06:00
Brad Groux
a6199faac0 docs: add deployment guide (Docker, bare metal, env config) 2026-01-29 01:39:58 -06:00
Brad Groux
1a9d406e5f fix(security): redact plaintext credentials from task data and audit doc 2026-01-28 17:06:59 -06:00
Brad Groux
b6fadfaa4c docs: add security, performance, and quality audit reports 2026-01-28 16:59:09 -06:00
Brad Groux
7dcc78a325 docs: add comprehensive code review findings
Full review covering security, performance, architecture, standards,
testing, and deployment readiness. Created sprint tasks for all findings.
2026-01-28 11:24:47 -06:00
Brad Groux
3efa474eb0 feat(server): Add authentication & authorization system
- Add auth middleware (server/src/middleware/auth.ts)
  - API key authentication via Bearer token, X-API-Key header, or query param
  - Role-based authorization (admin, agent, read-only)
  - Localhost bypass option for development
  - WebSocket connection authentication

- Update index.ts to integrate auth middleware
  - Apply authenticate middleware to all /api routes
  - Add /api/auth/status endpoint for diagnostics
  - Protect WebSocket connections with token validation
  - Display auth status in startup banner

- Add configuration via environment variables
  - VERITAS_AUTH_ENABLED (default: true)
  - VERITAS_AUTH_LOCALHOST_BYPASS (default: false)
  - VERITAS_ADMIN_KEY for admin access
  - VERITAS_API_KEYS for named keys with roles

- Add comprehensive security documentation (docs/security.md)
- Add .env.example with all auth configuration options

Closes RF-01
2026-01-28 07:37:44 -06:00
Brad Groux
01e0e29eb9 docs: Sprint 1150 Settings Hardening documentation update
- Created comprehensive settings-architecture.md covering:
  - Component hierarchy and responsibilities
  - Data flow and state management
  - Security measures (XSS, path traversal, prototype pollution)
  - Accessibility features (WCAG 2.1 AA compliance)
  - Error handling strategy with boundaries
  - Performance optimizations (lazy loading, memoization)
  - Code organization patterns

- Updated CHANGELOG.md with Sprint 1150 entry (v0.9.0)
  - All 8 user stories documented
  - Security, accessibility, and performance highlights

- Updated README.md with Settings & Customization section

Sprint 1150 Code Quality Assessment:
✅ TypeScript: 0 compilation errors
✅ Architecture: Clean component extraction, no circular deps
✅ Security: Strict validation, sanitization, rate limiting
✅ Accessibility: WCAG 2.1 AA compliant
✅ Performance: Lazy loading, memoization, debouncing
✅ Error Handling: Isolated error boundaries per tab
⚠️  Tests: 161 failures in worktree directories (unrelated to Sprint 1150)
2026-01-28 04:24:23 -06:00
Brad Groux
0c12bacbf2 docs: Sprint 12-14 planning — LAN access, status indicator, metrics refactoring
Sprint US-1200 (6 stories): LAN access — Vite/Express binding, CORS,
  firewall, auto-detect URL, responsive audit
Sprint US-1300 (6 stories): Working indicator — status API, animated
  component, real-time hook, Veritas integration, history, header layout
Sprint US-1400 (7 stories): Metrics refactoring — telemetry ingestion,
  reporter, service refactor, task metrics, dashboard refresh, run badges,
  cost tracking

All three feature requests investigated, documented, tasks created with
subtasks, sprint docs written.
2026-01-28 02:06:58 -06:00
Brad Groux
a81dfecadf docs: expand Sprint 10 with agent comparison, failure alerts, daily digest, budget tracking, velocity 2026-01-27 20:34:42 -06:00
Brad Groux
9c883d0f10 docs: Update sprint-9 status to Complete (8/9 stories)
US-907 (Apply template to existing task) deferred - requires significant TaskDetailPanel changes. All other stories completed successfully.
2026-01-27 20:33:48 -06:00