Org Studio v0.4.1

This maintenance release aligns the repository with the approved 2026-07-16
product direction and hardens the continuing 0.x release line.

Highlights

- Focuses Org Studio on persistent, named OpenClaw and Hermes teams in trusted
self-hosted environments.
- Synchronizes the checked-in vision with the live vision and adds a scheduled
drift check.
- Records the Materialyze transfer inventory and equivalence gates. No
Materialyze-bound prototype code is deleted before transfer.
- Keeps file mode as the zero-database local start and PostgreSQL as the
durable multi-user option.
- Replaces new unsalted SHA-256 password records with salted scrypt and
transparently upgrades legacy records after successful login.
- Binds the custom server to loopback by default and refuses unauthenticated
non-loopback startup unless the isolated-network escape hatch is explicit.
- Defaults PostgreSQL workspace enforcement to strict.
- Updates Next.js, ws, and transitive dependencies; npm audit reports zero
vulnerabilities.
- Adds macOS tests, Docker build, dependency audit, and stable aggregate
required checks to CI.
- Fixes macOS Bash 3.2 skill synchronization and incorporates the useful
maintenance changes from former PRs #83, #86, #88, and #89.

Validation

- 112 test files passed
- 1,479 tests passed; 1 skipped
- TypeScript and production build passed
- Ubuntu and macOS CI passed
- Docker image build passed
- Version and live-vision checks passed
- Full dependency audit passed with zero vulnerabilities

Product boundary

Worker runtime, direct coding engines, provisioning, HostProfile,
RepoContextPack, planner, model-tier routing, receipts/worker scorecards, and
runtime-independent messaging remain transitional. Their transfer-first plan
is documented in
docs/decisions/2026-07-16-materialyze-separation.md.

Full changelog: https://github.com/ToomeSauce/org-studio/compare/v0.4.0...v0.4.1

[0.4.0] — 2026-05-23

Three-week stabilization pass between 0.3.3 and 0.4.0 focused on scheduler reliability, dispatch read-path performance, comment-storage hardening, and observability. 30 commits across 5 themed clusters. No public-API breakages.

Headline shifts

1. Dispatch correctness is structurally solid. Snapshot staleness eliminated at dispatch time (#1515), status_history writes are atomic (#1531), all 7 dispatch paths emit unified [dispatch #1515] telemetry (#1521), and every status-change writer routes through a single buildStatusTransition() helper (#1535). Inline @mention dispatch in server.mjs is gone (#1513) — only the durable Postgres-backed dedup + audit table fires.
2. Scheduler hot path is ~3.5× thinner on the wire. PostgresStoreProvider.read() is slim+parallel by default (#1520), the case 'trigger' decision path uses readSlim() only (#1529, 3.2MB → ~900KB, 619ms → 143ms p95), and fireOneShot() uses readSlim() + new targeted getTasksForAgent() (#1534). The wire footprint for cross-agent gate-signal evaluation is now indexed columns, not full-fat JSONB blobs.
3. Comments are auditable. Every comment write captures authentication-side metadata (authMethod, userId, tokenId, apiKey hash, IP, UA, requestedAuthor pre-canonicalization, capturedAt) and persists it server-side only (#1506). New admin endpoint to query the audit log (#1508). Defense-in-depth: auditMeta is stripped from every list/read response.
4. listComments is a first-class read API. New normalized org_studio_comments table backs listComments and bulk listCommentsForTasks (#1524). API now accepts agent-friendly taskId shorthand and returns an actionable error hint when the scope shape is wrong (#1536). Phase 2b/3 (stop inline task.comments[] write, drop the JSONB column) remain blocked on human sign-off — both are irreversible.

Added

#### Reliability & correctness
- Postgres-backed durable notification dedup + structured audit table (#1513) — replaces in-memory dedup. Comment / mention / status notifications flow through the normalized path with recency suppression for stale-on-arrival events and latency logging.
- Re-read store at dispatch time (#1515) — eliminates snapshot staleness when the dispatcher fires; dispatch fingerprint narrowed to actionable buckets only.
- Lease guard honors human/QA STOP comments (#1492) — explicit STOP comment on an in-progress task pauses the lease until cleared.
- Level-3 auto-bounce write reliability + activity-feed surfacing (#1493).
- Wake assignee on any non-in-progress → in-progress transition (#1494) — closes a gap where dev was silently re-dispatched from done/review without a wake event.
- buildStatusTransition() helper (#1535) — every status-change writer (route handlers, scheduler, sweeper, blocker-clear, dispatcher) now routes through one pure helper that owns statusHistory append, lastActivityAt bump, loopCount/loopPausedAt reset, and claim-lease stamping on entering in-progress. Reduces the bug surface for the long tail of status-write paths.
- status_history appended atomically with typed status flips (#1531) — closes the race where a successful status update could lose its history entry on concurrent writes.

#### Performance
- PostgresStoreProvider.read() slim+parallelize (#1520) — 2.15× faster baseline read. data JSONB still included on overflow paths via #1520 follow-up so subscript indexing into custom fields keeps working.
- PostgresStoreProvider.readSlim() (#1529) — projection-narrow read for hot paths that don't need full task bodies; ships ~900KB instead of 3.2MB at workspace scale (1400 tasks, 8 agents).
- PostgresStoreProvider.getTasksForAgent(name, id) (#1534) — single targeted SELECT with full columns for one agent's non-archived tasks (lower(assignee) IN (name, id)). Used by fireOneShot() to ship full-fat blobs only for the agent being dispatched.
- Request-scoped store-read memoization for case 'trigger' (#1526) — collapse N read calls within the same request to 1.
- Parallelize hydration query + prewarm pg pool at boot (#1528).

#### Comments & audit
- auditMeta on every comment write (#1506) — authMethod, userId, tokenId, short apiKey hash, requestIp, userAgent, requestedAuthor (BEFORE canonicalization), capturedAt. Persisted server-side only; never returned to clients (route-layer stripAuditMeta defense-in-depth).
- GET /api/admin/comment-audit (#1508) — admin endpoint to query the audit log by taskId, apiKeyHash, time range, etc. Inner-auth 401 downgraded to uniform 403 admin_required to avoid leaking which keys are admin vs. valid-but-non-admin.
- Bulk listCommentsForTasks + migrate evidence/signal detectors (#1524) — Phase 2a. Detectors that previously scanned task.comments[] JSONB now hit the normalized table via a single bulk fetch.
- listComments accepts taskId shorthand (#1536) — agents can pass {action:"listComments",taskId:"<id>"}; the server auto-promotes to {kind:"task",taskId}. The 400 response now includes an actionable hint field explaining the expected shape ("comment scope, not auth scope"). Backward-compat: explicit payload.scope always wins.

#### Observability
- Notification-health admin dashboard (#1516) — visualizes dedup hit rate, notification latency, and per-agent delivery counters.
- [dispatch #1515] telemetry hoisted inside fireOneShot() (#1521) — all 7 dispatch entry points (cron tick, manual trigger, blocker-clear, etc.) now emit the same diagnostic line.

Changed

- Scheduler write path uses targeted per-row writes (#1497) — writeStore() full-store-rewrite replaced with row-scoped provider.updateTask() / provider.upsertProject() calls. Eliminates a long-standing lost-write race on concurrent scheduler ticks.
- listComments error message (#1536) — was {error:"Missing scope"}; now includes hint explaining that this is a comment scope, not an auth scope, and pointing at the canonical shape. Error string unchanged for any caller pattern-matching on it.
- Inner-auth response on admin endpoints (#1508) — 401 with method-specific message → uniform 403 {error:"admin_required"}. Reduces enumeration risk.
- Optimistic version-approval state (PR #46) — UI now reverts optimistic state when the server rejects the write, instead of leaving the version in a phantom-approved state until refresh.

Removed

- Legacy inline @mention dispatch in server.mjs (#1513) — the path that bypassed Postgres dedup and the audit table. Comments and mentions now route exclusively through the durable path.
- Team Activity section from home page (#1495 bug 3) — unused, occupied prime above-the-fold real estate.

Fixed

- Archived filter on context board showed zero results (#1495 bug 1).
- Top nav unpinned from viewport (#1495 bug 2) — h-screen on a flex parent with unbounded body content broke sticky top-0 on the nav.
- Model badges missing on Billy/Thelma comments (#1495 bug 4) — wrong port + auth wall in the badge fetch.
- .ts import path in #1529 parity verifier (#70ba554) — broke deploy-time typecheck.
- data JSONB included in slim task SELECT (#1520 follow-up) — restored overflow-read behavior for tasks that store custom fields in data.

Skill (org-studio-api)

- listComments documented for the first time — Quick Reference table entry + canonical shape + taskId shorthand. Closes the agent-confusion root cause behind #1536 (the API existed; the skill never explained it, so agents pattern-matched the wrong shape from addComment).
- references/api-reference.md — new POST /api/store — listComments section with full request/response examples, both shapes, and the 400 hint.

Notes

- Skill bundle (skills/dist/org-studio-api.skill) rebuilt via npm run build:skill. SHA sidecar captures package_version=0.4.0, git_sha=<release-sha>, built_at, size_bytes. Publishing to ClawHub still requires a human with publish credentials (#1466, blocked).
- Phase 2b (#1294, stop inline task.comments[] write in addComment) and Phase 3 (#1295, drop org_studio_tasks.comments JSONB column — irreversible) remain in blocked. Both await human sign-off on the migration cutover plan. The normalized org_studio_comments table is the live read path as of #1524; the inline JSONB write is now redundant.
- Single git revert rollback is still possible for any of the 30 commits in this release; the comments-migration tickets that aren't reversible (#1295) are explicitly held in blocked until they are individually approved.

Docs-only follow-up to v0.3.2. Rewrites the Local Environment: Host Constraints section of org-studio-api/SKILL.md to describe only the general pattern — no operator-private hostnames or hardware caveats. Operators with specific constraints should add them to their own AGENTS.md / workspace overlays rather than to the shared skill.

Changed

- Local Environment: Host Constraints in SKILL.md — generic, deployment-agnostic version. Same preferred validation workflow (targeted local checks → push → let CI build → gh run watch), same self-check rule, same CI-fallback. Removed: hostnames, hardware descriptions, deployment-specific anecdotes.
- CHANGELOG entry for v0.3.2 — same wording correction.

Notes for adopters

- v0.3.2 git history and release notes still contain the original wording. This is a forward-only correction.
- If you maintain an Org Studio deployment with host-specific constraints (thermal limits, memory caps, shared CPU), document them in your local AGENTS.md / per-workspace skill overlay rather than upstream.
- No runtime changes. No DB migrations. No env changes.

Full Changelog: https://github.com/ToomeSauce/org-studio/compare/v0.3.2...v0.3.3

> ⚠️ Superseded by v0.3.3. The Local Environment: Host Constraints section in this release included deployment-specific details (a hostname and hardware caveat) that should not have been in the shared skill. v0.3.3 rewrites that section to describe only the general pattern. Please use v0.3.3 or later.

---

Docs-only. Crystallizes host-specific build constraints into the org-studio-api skill so every Org Studio agent picks them up automatically on session start.

Added

- Local Environment: Host Constraints (READ BEFORE BUILDING) section in skills/org-studio-api/SKILL.md, placed top-of-file (right after Event-Driven Triggers, before Quick Reference).

Documents the hanktank rule (older Mac Mini that thermal-shutdowns on full builds):
- Forbidden: next build, full vitest / npm test, full-project tsc --noEmit, full-repo eslint, anything that compiles/bundles/lints/typechecks the whole project
- Allowed: targeted single-file checks, next dev, git ops, focused scripts, db queries
- Preferred workflow: push → let GitHub Actions CI run the full build → gh run watch → fix from CI logs
- Self-check rule before running build-like commands
- Fallback: if CI doesn't exist for a repo, create/repair .github/workflows/ci.yml rather than running a full local build

Explicitly notes the rule is hardware-specific (host=hanktank only). Other hosts can run full local builds freely.

Why

The hanktank rule was being learned ad-hoc per agent. Putting it in the shared skill means every agent on every Org Studio project picks it up automatically — no per-agent memory edits, no drift.

Notes for adopters

- No runtime changes. No DB migrations. No env changes.
- The .skill bundle attached to this release has the new section included.
- Agents already running pick it up on next dispatch via the workspace skill cache rsync pattern.

Full Changelog: https://github.com/ToomeSauce/org-studio/compare/v0.3.1...v0.3.2

Docs + release-tooling pass. No runtime changes.

This release follows up on the v0.3.0 ship by bringing the public org-studio-api skill back in sync with the API surface that landed in #1461, and by making future skill releases reproducible.

Added

- org-studio-api skill refreshed for #1461. SKILL.md + references/api-reference.md now document:
- action: "create" — strict, title-required, owner-inherited from project
- action: "patch" — COALESCE-by-default with items_mode: replace | merge for list fields
- versionType values qa and gtm (in addition to the existing types)
- The single-current invariant (one in-flight version per project)
- The new /api/admin/roadmap-audit admin endpoint
- scripts/build-skill.sh + npm run build:skill — single-command, reproducible build of skills/dist/org-studio-api.skill with a org-studio-api.skill.sha sidecar capturing package_version, git_sha, built_at, and size_bytes. Replaces the April-vintage stale zip that had been sitting in the repo.
- README "Publishing the org-studio-api skill" section — release flow is no longer tribal knowledge.

Fixed

- workspace-auth-browser.test.ts (#1467) — was failing on main since 2026-05-18 because the test mocked getStoreProvider() but the impl calls getStoreProviderAllWorkspaces(). Mock both factories against the same fixture; suite is back to 631/631 green. CI gating is unblocked.

Docs

- CHANGELOG backfill for v0.3.0 (#1468) — the v0.3.0 release bumped package.json without a CHANGELOG entry. Backfilled retroactively from git log 397c4a6..1b956cf (36 commits, 2026-05-05 → 2026-05-08). Headlines were: outcome-bound versions (#1263), two-state project model (roto54a), Postgres-only store (#1265), and task.priority field removal (#1249). See CHANGELOG.md for the full entry.

Notes for adopters

- Publishing the new skill bundle to clawhub.ai is tracked separately (still requires publish credentials). Locally you can npm run build:skill and the produced skills/dist/org-studio-api.skill (~20 KB) is the same artifact a future ClawHub publish would ship.
- No DB migrations. No env changes. Safe to deploy from main with npm run deploy.

Full Changelog: https://github.com/ToomeSauce/org-studio/compare/v0.3.0...v0.3.1

v0.3.0 — Outcome-Bound Versions + Postgres-First

35 commits since v0.2.0. The headline change: versions can now be bound to a measurable outcome that gates auto-promotion. Roadmaps stop pretending work is done when the metric says otherwise.

✨ Headline Features

Outcome-bound versions (#1263)

Tag a version with version_type: outcome, set a successCriteria string, a numeric metricTarget, and a comparator (gte / lte / eq). The roadmap won't auto-advance past that version until metricCurrent satisfies the gate — even if all child tickets are marked done. Defense-in-depth in project-state.ts blocks the explicit promote path too, so a Launch button click can't sneak past the gate. Pairs naturally with checkpoint versions for delivery work.

Update measurements with the +· button on the version row, or programmatically via updateRoadmapVersion.

Postgres-first storage (#1265)

data/store.json retired as a runtime fallback. When DATABASE_URL is set, Postgres is the single source of truth — no more silent stale-data reads when Postgres is briefly unreachable. File mode is now an explicit dev/offline path, labeled as such in Settings. Final archive of the legacy file lives at data/backups/store-1265-final-archive-*.json for any forensics you still need.

Per-component owner pickers (#1216 follow-ups: #1280, #1276)

Every version on the dashboard — current and planned — now exposes an inline owner picker. The current-version picker is wrapped in a labeled OWNER · name ▾ chip on the right of the row, so it's unambiguously a control rather than blending into the metric pills. Edit and delete buttons added to the current-version block to match planned versions (#1276).

Editable project metadata (#1281)

A settings slide-over (/projects/[id] → ⚙️) lets you rename a project, change its description, default owner (component fallback), vision owner, and repo URL without touching the JSON.

Two-state project model (roto54a)

Projects collapsed to a single Active/Inactive toggle. The "Launch button" workflow that lived alongside backlog/in-progress is gone. Projects are either being worked on or archived — and the launch ceremony has been folded into version-level promotion (which is now gated by outcomes anyway, see #1263).

npm run deploy (#1261)

Single command does build → restart → health-check → print BUILD_ID + SHA + branch. Boot logs now include a [boot] org-studio dashboard live: BUILD_ID=… SHA=… line so you can verify the running process matches git rev-parse --short HEAD after a deploy. Variants: --skip-build (restart only), --no-restart (build only).

🔧 Notable Fixes & Improvements

- #1267: rename a roadmap version in place instead of duplicating it
- #1266: blocked-task deep links across /projects, project dashboard, and /context
- #1268: auto-notify the dev owner on every non-system ticket comment
- #1269: addTask / updateTask now auto-resolve sectionId from project + component when omitted
- #1262: assignee notifications use a richer "reply on the task" envelope
- #1260: surface /api/store errors instead of silently dead buttons
- #1253: Activate button — optimistic state + error toast + double-click guard
- #1250: vertical drag-and-drop within columns + dispatcher reads sortOrder
- #1249: removed task.priority field — column-position is the canonical signal
- #1248: mobile fixes — task detail panel x-jitter + project header overlap
- #1254: orphan-blocked tasks — rehome UI + project-scope opt-in
- #1235: orphan blocked tasks now surface on the project dashboard
- #1234: rename proj-mc → proj-org-studio + reject unknown projectId on addTask
- #1229: auto-mint stub vision doc + rv-table row on first launch
- #1230: rip Telegram-proposal relic out of launch message
- #1194: diagnoseAgentBacklog exposed via /api/scheduler?action=diagnose

🧪 Test Coverage

486 tests across 34 files. New coverage locked in for assignee auto-notification (#1246), approvedVersions[] set-membership gating for auto-promote (#1222), and approvedVersions[] ComponentFixture type alignment (#1224).

🧭 Upgrade Notes

- Postgres users: nothing to do beyond pulling — file fallback retirement is invisible if you've already configured DATABASE_URL.
- File-only / dev users: still works, but the Settings panel will explicitly flag your install as offline-mode. Set DATABASE_URL to switch to durable storage.
- Anyone using outcome-bound versions on existing data: existing versions default to version_type: checkpoint and continue to behave as before. Opt in per-version via the version edit form.
- Migrating from v0.2.0: no schema migrations required; everything is additive.

— Mikey

Changelog

All notable changes to Org Studio. Format loosely follows Keep a Changelog; versioning is SemVer (pre-1.0 — minor bumps may include breaking changes).

[0.2.0] — 2026-05-05

First substantive release since v0.1.1. The headline shift is per-component roadmaps: every project can now have multiple Components (Main / QA / Frontend / Backend / etc.), each with its own version timeline, approval list, and dispatch gates. The legacy single-roadmap-per-project model is gone.

Added

#### Per-component roadmaps (#1112, #1126)
- Component type with own versions[], owner, role, and approvedVersions[]
- Stacked per-component roadmap UI on the project page, with component filter pills
- Per-component dispatch gating in the scheduler — each component's approvals govern its own tasks
- version.owner field with getEffectiveOwner() helper; assignee snapshot-on-create
- Sequential dispatch gate (a version can't dispatch until prior approved versions on the same component have shipped)
- Editable component owner + per-version owner UI

#### Approval model (#1188, #1212, #1224)
- Per-version approval checkboxes replace the draggable approval banner — non-contiguous approvals are now first-class
- approvedVersions[] (explicit set) is the sole source of truth for dispatch eligibility
- Legacy approvedThrough scalar and its contiguous-prefix semantics removed (#1224)
- Skipping an unapproved version no longer blocks a later approved one (#1212)
- "Approve & Start v…" CTA replaces dead-end disabled Start button

#### Dispatch & scheduler (#1100, #1102, #1138, #1180, #1183, #1184, #1204)
- Adhoc-task dispatch lane (followups/bugs without a roadmap version)
- Dispatch attempt logging + diagnose-blocker API (phase 1)
- Dispatch banner + per-ticket badge + Telegram escalate (phase 2+3)
- Auto-unblock fan-out on blocker completion
- Stall heuristic v2 — time-based + stale-claim aware
- Hard SINGLE-WIP gate at dispatch boundary (#1204)
- Watchdog stops re-dispatching dormant agents + only logs real restarts

#### Health & observability (#677, #678, #679, #861, #864, #982, #983)
- System Health page + /api/health endpoint
- Periodic roadmap reconcile cron + /api/health/roadmap
- Outbox + retries for gateway sends; agent loop heartbeat watchdog + incidents table
- Skill-install-ping instrumentation; ORG.md generator emits sha256 + timestamp
- Bootstrap-ping reports file SHAs at session start
- pubsub: heartbeat + auto-reconnect + health endpoint
- Vision doc GET/PUT structured logging
- Scheduler exposes in-flight state + sweep results
- Build SHA pill in sidebar

#### Workspaces & multi-tenancy (v0.16, #719)
- File-store workspace envelope with silent auto-migration
- Per-workspace auth, projects, teammates, threads isolation
- Workspace memberships seed script
- Login workspace cookie

#### UI / UX
- Projects page regrouping: Blocked / Active / Inactive / Archived (#1190)
- Home page cleanup — drop Mission, rename to Blockers + Active Projects (#25, #26)
- Home Blockers shows only user-owned blockers + agent blocker protocol (#1192)
- Project-page Components panel + board filter pills
- Studio Ledger editorial project page (cutover) (#1)
- Operations dashboard replaces default ledger view on project page (#11)
- Responsive Settings modal + TopBar user menu
- Telegram nudge to vision owner on version-shipped (#1191)
- Mobile horizontal-overflow fix (#12)

#### Data / migrations
- project.state field, inFlightRunId on tasks, project-state.ts util
- Atomic ticketNumber allocation via Postgres sequence (#863)
- Roadmap data hydration + QA collapse migration trio
- Backfill roadmap_sort_order to semver-aware keys
- Thrivor migration + test-project cleanup
- Semantic-versioning migration (0.141 → 0.14.1, drop v prefix)
- Auto-advance: trigger promote when approvedThrough changes; auto-stop when all approved work ships
- Roadmap-sync: keep embedded items in lockstep with rv-table; serialize concurrent item-done writes (#1181)

#### Comments / mentions
- Mentions exclude email addresses
- OpenClaw agents get mention text via chat.send (not just scheduler wake)
- Reliable @mention dispatch via commentId in NOTIFY
- Multi-human safe author resolution (#1218)
- Comment empty-body guard + auth-method-aware author resolver (#1217)

#### API hardening
- updateTask validates payload shape and returns 404 on missing id (#1195)
- Adhoc-lane version bypass closed + symmetric updateTask validator + audit script (#1211)
- addTask: auto-promote planning → backlog when task matches currentVersion
- blocked transitions require non-empty blockedReason (#1138 follow-up)

Changed

- KISS board simplification: 5 columns (Planning / Backlog / In Progress / Review / Done); QA is a component, not a column. Review is opt-in only for irreversible or security-sensitive changes. Blocked is its own status.
- Telegram comms relay disabled by default; health-alerts moved to webhook
- Removed in-app chat/DM feature (workspace envelope made it obsolete)
- Sidebar cleanup — Settings/Logout moved out of sidebar
- Consolidated all promote-version paths into promoteProjectToNextVersion
- Scheduler prompt updated for KISS board

Fixed

- Component-aware approval banner writes; Start button gate respects components
- Self-governed components bypass project-level dispatch gates correctly
- waitsFor target treats untagged legacy tasks as primary component
- Synthesize roadmap cards for QA/support components
- Hydrate component.versions[] from rv-table on read (close shadow-roadmap drift)
- Refresh non-primary component version fields from rv-table on store read
- NOTIFY org_studio_change on roadmap mutations so clients refresh
- Roadmap version edit hardened against undefined item.title / version fields
- Scheduler: blocked tasks are now visibility-only in dispatch (#1100)
- Store: bulk write() was nulling version column on every task; same bug in createTask — fixed
- Auto-advance: handle 0-item versions
- Vitest: 8 store-provider/store-logic failures repaired (#1145)
- Plus ~40 smaller guard / null-safety / UI polish fixes

Removed

- Legacy approvedThrough scalar (project + component level) — fully gone, data migrated
- role:qa carve-out from dispatch gate (#1126 PR 6) — QA tickets go through the same path as everyone else
- Single-roadmap-per-project model — replaced by Components

Migration notes

Existing deployments will auto-migrate on first boot:
- Project file stores wrap into a workspace envelope
- approvedThrough values backfill into approvedVersions[]
- Roadmap items get auto-minted ids and semver-aware sort_order
- Versions normalize to SemVer (e.g. 0.141 → 0.14.1, v prefix dropped)

No manual action required for self-hosted instances.

---

[0.1.1] — 2026-04-17

Last minor release before the per-component roadmap arc. See git log for details.

[0.2.0]: https://github.com/ToomeSauce/org-studio/compare/v0.1.1...v0.2.0
[0.1.1]: https://github.com/ToomeSauce/org-studio/releases/tag/v0.1.1

Fixes since v0.1.0

Hermes Agent Support
- ORG.md + skill now syncs to Hermes agent workspaces (~/.hermes/profiles/{name}/workspace/)
- Hermes workspace path resolved before OpenClaw fallback
- ORG.md syncs on all store events (not just store_update)

Auto-Notify Project Owners
- devOwner + qaOwner auto-notified on every task comment they didn't write
- No @mention needed — notifications are automatic
- Skips duplicate if owner was already explicitly @mentioned

Task Ownership
- Only the assignee can move a task to done (403 if someone else tries)

Skill Updates
- Cross-project blocker guidance (any agent, not just QA)
- Append (#NNN) ticketNumber to roadmap item titles for deep-linking
- ORG.md tells agents to re-install skill every session (npx skills add ToomeSauce/org-studio --yes)

Root Cause Cleanup
- done derived at read time from linked task status — no more stale flags
- Removed dual sprint completion systems (server.mjs watchdog deleted)
- Removed auto-advance — human must click Launch for every version
- Shared in-flight tracking prevents dispatch lock stalls
- Idle backlog sweep catches dropped chains within 10 minutes
- Title-match fallback removed from roadmap sync (taskId-only)
- ~600 lines of dead code removed

UI
- Disabled Launch button with "All approved versions shipped" message
- Launch respects approval horizon — can't launch unapproved versions
- Context board columns sorted most-recent-first
- Roadmap status emojis: 👀 in-progress, 🟡 review, 🔴 blocked, 📝 draft
- Runtime agent picker dropdown replaces free-text agentId on Team page
- Priority dropdown removed from add-task form

What's New

v1.4: Agent Metrics Infrastructure

- Daily agent metrics table with automated midnight cron
- GET /api/metrics/{agentId} and GET /api/metrics/team endpoints
- Mention response time + cross-agent collaboration tracking
- Historical backfill from existing task data

v1.5: Performance Dashboard

Full /performance page with 7 sections:
- Team Health — velocity trend, activity heatmap, stall detection, review bottlenecks
- Quality Scorecard — first-pass rate, reviewNotes rate, testPlan coverage, clean streaks
- Cultural Alignment — PACT values breakdown, agent×value heatmap, weekly timeline, auto-principles
- Agent Comparison — sortable table with SVG sparklines and CSV export
- Version Velocity — time-to-complete per version with project filter
- Agent Cards — click for daily trend charts drill-down
- Team Summary — aggregate stats at a glance

v1.6: Metrics-Driven Coaching

- ORG.md Performance injection — agents see You vs Team Avg table + 7-day trend every session
- Coaching insights engine — 8 pattern detectors (throughput trends, bounce rate, comment activity, consistency, hot streaks)
- Metrics-based achievement detection — milestone streaks, perfect weeks, high-volume days, throughput leader, fastest version → auto-creates kudos
- Weekly team digest — auto-generated summary with Telegram delivery (POST /api/metrics/weekly-digest)
- Auto-pause projects when all approved versions complete (no more stale-launched state)
- org-studio-api AgentSkill — installable API reference for any agent (npx skills add ToomeSauce/org-studio)
- Fixed kudos count showing ⭐ 0 on agent cards (3 root causes: string coercion, zero-activity skip, agentId mismatch)

Docs

- Full refresh of README, architecture, performance, vision-cycles, and agent-api docs
- docs/agent-api.md now points to the canonical skill reference
- Skill auto-syncs to agent workspaces alongside ORG.md

---

22 commits since v1.3.2 | Full changelog

24/7 Agent Reliability

• SSE inactivity timeout — If a Hermes run crashes (API timeout, process error) and the SSE stream hangs without sending run.completed/run.failed, a 5-minute inactivity timer detects it and clears the in-flight state. Recovery time reduced from 30 minutes to 5 minutes.
• Dispatch retry on unreachable — When an agent's runtime is temporarily unreachable (e.g., process restarting for config changes), fireOneShot retries 3 times with backoff (15s → 30s → 60s) instead of giving up and waiting for the 30-minute watchdog sweep.
• Remote task creation triggers dispatch — Postgres createTask() now emits a NOTIFY event, and the LISTEN handler processes task_created events to trigger the assigned agent. Tasks created from staging/remote UI now dispatch agents immediately (previously silent until the next watchdog sweep).

Cross-Project Blocker Workflow

• Reassignment trigger — Reassigning an in-progress task to a new agent now dispatches them immediately (previously only backlog assignments and QA bounces triggered dispatches).
• ORG.md blocker protocol — New "Cross-Project Blockers" section in every agent's ORG.md:
1. Mark your task as blocked
2. Create a new task in the blocking project for that project's dev owner
3. Dev owner fixes + uses addHandoff to inject context back
4. Auto-unblock and re-dispatch
Explicitly prohibits reassigning tasks across project boundaries or fixing code in projects you don't own.

Fix: Agent Dispatch Loops

Auto-chain dispatch was re-dispatching agents who already had in-progress tasks, causing repeated interruptions and false-positive loop detection pauses.

Root cause: When a Hermes run completed (including mention responses), the onComplete callback checked hasActionableWork() which returned true for in-progress tasks — triggering another dispatch that interrupted the agent mid-work.

Changes:

• Smart auto-chain: getActionableWork() now distinguishes NEW work (backlog/QA) from EXISTING work (in-progress). Auto-chain only dispatches for new work — in-progress tasks mean the agent is already working.
• Comment-aware loop detection: If an agent posts a comment since their last dispatch, loopCount resets — comments prove progress even without a status change.
• Raised loop threshold: 3 → 6 dispatches before pause. Complex tasks (infra, multi-file refactors) need more room.

Real-Time Activity Feed

• Live activity stream on the home page — task status changes, version completions, and Hermes agent tool calls
• Click any agent in Team Activity to filter the feed to their work
• Tool call grouping reduces noise (collapses consecutive calls from the same agent)
• Seeded from task statusHistory on startup (works in both local and cloud deployments)
• WebSocket real-time updates with HTTP fallback

Cross-Runtime @Mentions

• @AgentName in task comments notifies the mentioned agent instantly
• Works across runtimes: OpenClaw → Hermes, Hermes → OpenClaw, and same-runtime
• Mentions from remote UI (staging/cloud) route through Postgres LISTEN handler to local agents
• Hermes agents resolved from filesystem config (~/.hermes/profiles/*/config.yaml)

Telegram Notifications

• Switched from Gateway RPC (broken for Hermes) to direct Telegram Bot API
• Agent comment replies now notify humans via Telegram (💬 Gem commented on "Task X")
• Task status notifications reduced to high-signal only (blocked tasks)
• Version lifecycle notifications: 🏁 auto-launch, ✅ roadmap complete

Project Organization

• Needs Attention category on projects page — projects with tasks in review or blocked surface at top with amber pulse
• Sprint stall indicator on project detail — amber border + banner when tasks await review
• Review/blocked tasks are clickable deep links to the context board
• Real task status icons in roadmap (👀 review, 🚫 blocked, ⚙️ in-progress, 🧪 QA)

Docker & Staging

• Dockerfile rewritten — dropped standalone mode, runs server.mjs directly with full node_modules
• Staging now has full feature parity: WebSocket, activity feed, mentions, scheduler, notifications
• Azure Container Apps configured with sticky sessions for WebSocket support

UX Polish

• Steady green dot for online agents (replaced pulsing)
• Green dot now checks 3 signals: activity-status API, in-progress tasks, and recent task history
• Comment send button prevents duplicates (disabled while submitting)
• Comments emit to activity feed for real-time dashboard visibility

Hermes /v1/runs Integration

• Switched Hermes dispatch from blocking /v1/chat/completions to async POST /v1/runs — returns run_id instantly (HTTP 202), processes agent turns in the background
• Real-time SSE event monitoring: tool calls (read_file, terminal, search_files), completion, and failure events streamed live
• Eliminates all fire-and-forget workarounds, silent fetch failures, and request piling

Auto-Chain Task Dispatch

• When an agent completes a task, the next backlog task dispatches immediately — no more waiting for the 30-minute watchdog sweep
• Agents now chain tasks continuously: Task A → complete → dispatch Task B → complete → dispatch Task C
• Significant throughput improvement for autonomous workflows

Notification Routing

• Task status notifications now reach Telegram for all agents, including Hermes agents (previously silently lost)
• Version completion alerts: 🏁 auto-launch notifications and ✅ roadmap complete notifications pushed to Telegram

UX Overhaul

• Home page: Mission statement moved to top; green dot derives status from in-progress tasks with actual task title + project name
• Projects page: Categorized into Active Sprints (animated pulse), Sprint Complete, Other Projects; removed flat sort-by-date list
• Sidebar: Cleaned up — removed expandable project sub-list
• Team page: Consistent 1-hour activity window + in-progress task check for online status
• Roadmap: Shipped versions now expandable with full item list; active projects show pulsing green dot on Current badge
• Context board: 3-second suppression after mutations prevents visual snap-back from WebSocket updates

Bug Fixes

• Archived tasks no longer show agents as "active"
• Needs Attention section filters archived tasks and tasks with no updatedAt
• Scheduler triggerAgentLoop auth header fixed (was silently failing 401)
• Runtime registry auto-discovers agents on cold start after restart

Scheduler Reliability

• Auth header on triggers — triggerAgentLoop was missing the Bearer token, causing all event-driven retriggers to silently fail with HTTP 401. Agents stopped receiving work after their initial session expired.
• In-flight guard — fireOneShot now tracks dispatched agents with a 10-minute TTL, preventing duplicate dispatches from watchdog sweeps while an agent is already working.

Hermes Runtime

• Fire-and-forget dispatch — Hermes send() no longer blocks the scheduler for the full task duration. Dispatches the message in a background fetch and returns immediately. Prevents request pileup when tasks take >30 minutes.
• Auto-discover on send — Runtime registry now auto-discovers agents if not found in the agent map, fixing cold-start failures after service restart.

Self-Sufficient ORG.md

• ORG.md is now the single context file agents need from Org Studio — no separate AGENTS.md required
• New sections: Work Loop (6-step task workflow), Activity Status, Task Comments
• New context field on teammates — free-text domain notes (branch policies, repo paths, safety rules) injected directly into each agent's ORG.md
• Editable in Team → Detail Panel → Domain section

Agent Auto-Onboarding

• Newly detected agents now automatically get a scheduler loop created (previously only teammate records were scaffolded)
• Combined with ORG.md enrichment, new agents can start executing tasks immediately after detection

Bug Fixes

• Project edit modal snap-back — changing Backup Dev/QA (or any field) no longer resets when WebSocket store updates arrive
• qaOwner clear-to-None — selecting "None" for Backup Dev/QA now correctly saves

What's New

Onboarding Redesign

- Welcome step with value prop — "Stop assigning tasks to your AI agents"
- Streamlined 5-step flow: Welcome → Organization → Runtime → Team → Done
- Dark/light theme toggle during onboarding
- Conditional copy based on runtime detection (OpenClaw + Hermes Agent)

Multi-Runtime Support

- Runtime Abstraction Layer: AgentRuntime interface (discover/send/health/dispose)
- OpenClaw and Hermes Agent supported out of the box
- Extensible to any agent framework implementing the interface

Demo & Docs

- Dark theme demo GIF (onboarding, home, project detail, context board, team, projects)
- ?onboarding=true query param for demo/screenshot mode

Bug Fixes

- Light-mode code block highlighting in docs and blog
- Ping panel disabled state for cloud/no-runtime environments
- Server-side agent auto-scaffold parity for file + Postgres

Full Changelog: https://github.com/ToomeSauce/org-studio/compare/v0.1.0...v1.1.0

Version Reset

Org Studio has been reset to v0.1.0 to reflect a new architectural foundation. Previous 1.x releases are preserved in history.

What's New

Unified Outcomes & Versions
- Every roadmap version has a type: 🎯 Outcome, 🏗️ Foundation, or 🧹 Chore
- Outcome progress is derived from shipped outcome-type versions — no separate outcomes list
- One version = one outcome. KISS.

Planning-Aware Launch
- Planning tickets are created during roadmap discussions and linked via taskId
- Launch button moves planning tickets to backlog — no duplicate ticket creation
- Approval horizon blocks on versions with draft items (📝 = missing tickets)

Event-Driven Architecture (Simplified)
- Single completion system — store route handles version completion on task→done
- done derived at read time from linked task status — no stale flags
- Shared in-flight tracking prevents dispatch lock stalls
- Idle backlog sweep catches dropped chains within 10 minutes

Guardrails
- Only the assignee can move a task to done
- Project owners (devOwner + qaOwner) auto-notified on every task comment
- Launch respects approval horizon — can't launch unapproved versions

Removed (KISS Cleanup)
- Legacy outcomes UI (checkboxes, add form, pending outcomes banner)
- Auto-advance (human must click Launch for every version)
- Dual sprint completion systems (server.mjs watchdog removed)
- Title-match fallback for roadmap sync (taskId-only)
- ~600 lines of dead code

Skill

``
npx skills add ToomeSauce/org-studio --yes
``
ORG.md now instructs agents to re-install every session for latest updates.