mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
v0.17.0 — Wave 3: sandbox DB, DB isolation, mobile UI, cloud auth, X account, roadmap engine (#303)
* feat(sandbox): throwaway per-agent Postgres/Redis sandbox containers
Orchestrator-provisioned sibling containers per agent spawn
(SandboxProvisioner, roboco/runtime/sandbox.py). Per-project opt-in via
projects.sandbox_services (migration 057); master switch
ROBOCO_SANDBOX_DB_ENABLED, default-off, armed in the NAS compose only.
When active, ROBOCO_TEST_DB_* / ROBOCO_TEST_REDIS_* point at the sandbox
and the prod-creds gate-env injection is suppressed (sandbox replaces,
never coexists). Sandbox lifetime tracks the agent container: teardown at
every removal path, orphan janitor at startup + each reaper tick with a
grace window for mid-flight spawns. The pre-spawn stale-clear spares the
just-provisioned sandbox; provision pre-clears stale same-named
containers from a crash-missed teardown.
Panel: per-project sandbox-service switches in the edit dialog + feature
flag card entry.
* docs: CLAUDE.md entry for the sandboxed dev DB/Redis subsystem
* feat(security): isolate prod Postgres/Redis from agent containers (roboco_data network)
Second user-defined bridge roboco_data carries postgres+redis only; the
orchestrator is multi-homed (default + data). Spawned agents and their
sandbox sidecars stay on roboco_default and can no longer resolve or
reach roboco-postgres:5432 / roboco-redis:6379 (redis has no auth —
membership is its only containment). Normal bridge, so host-published
ports (15432/16379) keep working. Applied to both build composes and
the registry compose; docker-compose.yml re-synced byte-identical with
docker-compose.yaml (it had drifted by the sandbox flag block).
ROBOCO_DB_NETWORK_ISOLATED (config default false, armed alongside the
topology) suppresses the legacy _append_gate_env prod-creds injection:
under isolation those creds dead-end, and unreachable creds are worse
than none. DB-needing projects opt into sandbox_services instead. The
flag is deliberately not a panel feature flag - it must travel with the
compose networks: stanzas.
Preserved by construction: agent<->agent A2A and orchestrator->agent SDK
polls on :9000, MCP->orchestrator on :8000, ollama reachability, docker
exec/inspect (daemon socket), host port publishing.
* feat(panel): full mobile responsiveness pass
Shared primitives: useIsMobile (useSyncExternalStore, hydration-safe,
memoized matchMedia subscribe), ResponsiveTable table->card switch below
md (single subtree mounted, no duplicated interactive rows), scrollable
snap TabsList in the base primitive (justify-center-safe so the first
tab stays reachable on overflow), persistent md:hidden bottom tab bar
(Overview/Tasks/Kanban/Chat, safe-area padded).
Applied: card lists for tasks/projects/products/work-sessions/sessions
+ the three raw metrics tables; CEO approval queue / release proposal /
playbook review action rows stack on narrow; command-center reorders
approvals above the fold on mobile; task-header metadata wraps;
Communications + A2A become URL-driven single-pane drill-downs below lg
(fixes the unconstrained-height ScrollArea bug) with dvh heights;
recharts label density/radius adapts via useIsMobile; git diff viewer
gets mobile font + wrap toggle; vh->dvh sweep; chat composers get
safe-area-inset padding; dashboard main p-4 md:p-6 + pb-20 for the bar.
Verified at 375px on the built app: bottom bar, drawer, approval-first
overview, swipeable kanban tab strip. All gates green (eslint, tsc,
vitest 249, next build 24/24 routes).
* feat(auth): cloud auth via FastAPI Users (default-off, single-user cookie session)
ROBOCO_CLOUD_AUTH_ENABLED (default off) lets the panel/API be exposed
beyond localhost without changing the CEO's local no-login flow while
off — get_agent_context and the WS gate are byte-for-byte unchanged in
off-mode. On: header-trust dies for humans — any agent-role claim (ceo
or a privileged PM/board role) with no valid HMAC token or session
cookie is 401, closing the header-spoof hole on the host-published
:8000 port for every role. The agent-fleet HMAC path and the system
self-PATCH keep working unmodified in both modes.
Single seeded CEO user (migration 058 users table, UserTable), no
registration router — idempotent env-driven upsert at startup by PK.
Cookie transport (httponly/secure/samesite=lax) + a JWTStrategy bound
to a fingerprint of the current password hash (rotating the password
invalidates every prior session). Sliding 30-day session: every
authenticated request re-mints the cookie, so an active session never
expires — no unexpected logouts.
Panel: (auth)/login page + proxy.ts (Next 16 rename of middleware; probes
/auth/status over the docker-internal URL, fails open to off) gate the
dashboard; client.ts gets withCredentials + 401->/login. nginx unchanged.
Review hardening: broadened the on-mode rejection from ceo-only to every
non-CEO role without a valid token (was only closed when
ROBOCO_AGENT_AUTH_REQUIRED was also armed); Next-16 proxy.ts rename to
clear the middleware deprecation warning.
* feat(x): RoboCo X account engine — HoM drafts, per-post CEO approval (default-off)
ROBOCO_X_ENGINE_ENABLED (default off, inert without creds). Mirrors the
ReleaseManagerEngine held-artifact shape: XEngine drafts a post when a
release publishes (via a draft_release_post seam on ReleaseProposalService
.approve) and drafts replies to meaningful mentions (dedicated poll loop,
x_seen_mentions dedup ledger, per-cycle/open caps). Drafting is
local-model-only, clamped to 280 chars. Nothing auto-posts — every tweet
is a held task (source x_post/x_reply, confirmed_by_human=False,
Secretary-owned, dispatcher-skipped) the CEO edits/approves/rejects in a
panel queue.
The four OAuth 1.0a secrets live Fernet-encrypted in a singleton
x_credentials row (migration 059, all-or-nothing, API returns only
has_credentials); decryption is server-side, agents never hold creds or
egress. Hand-rolled OAuth 1.0a HMAC-SHA1 signer, no new dependency;
NullXClient makes the unconfigured path a graceful no-op.
XPostService.approve (CEO-only) is the sole caller of post_tweet.
Review hardening: closed a double-post race — the approve path now
re-reads committed task state inside the Redis lock and commits COMPLETED
before releasing, so a concurrent approve that acquires the lock after the
winner released can't re-post (SET-NX is non-waiting, and the route-level
commit landed after the lock dropped). Added a regression test.
* feat(roadmap): board roadmap engine — PO proposes themed cycles, CEO approves per-item (default-off)
ROBOCO_ROADMAP_ENGINE_ENABLED (default off). Weekly, RoadmapEngine opens
ONE held exploration task (source=board_roadmap, confirmed_by_human=False,
Product-Owner-assigned), deduped to one open cycle. A dedicated one-shot
_dispatch_roadmap_exploration spawns the PO solo (not the two-reviewer
board path, which would also spawn HoM + fire Approve-&-Start). The PO
explores read-only (git/KB/metrics/releases/charter/web) and makes one
propose_roadmap call (PO-only content verb) authoring a themed cycle —
goal + 3-7 item drafts — persisted as a roadmap_cycle marker (no table,
no migration; head stays 059).
The CEO acts per-item in the panel roadmap queue: approve materializes a
BACKLOG task (source=roadmap, no assignee — never auto-starts), reject
records a reason; all-items-terminal completes the exploration task.
RoadmapService is idempotent per item. Dispatchers skip board_roadmap.
Includes a real SQLAlchemy dirty-check fix (deep-copy the JSON marker
before mutating, or the in-place edit + reassign compares equal to its
own baseline and the UPDATE is skipped).
Review hardening: create_task_from_draft now honors a draft-declared
source only from a {prompter, roadmap} whitelist — drafts are
LLM-authored, so an unbounded source could impersonate a privileged
origin (release_manager would even wedge that engine's dedup).
* chore(release): 0.17.0
Wave 3 — six default-off subsystems: sandboxed dev DB/Redis, prod
Postgres/Redis network isolation, full mobile UI pass, cloud auth
(FastAPI Users), the RoboCo X account engine, and the board roadmap
engine. Plus the waves 1+2 work already on master since 0.16.0.
Version bumped across the canonical set (config.py, __init__.py,
pyproject.toml, panel/package.json, uv.lock); CHANGELOG [Unreleased]
cut to [0.17.0]; docs/map delta added.
Compose: every optional feature armed :-true in the NAS composes, OFF
in the user-facing registry compose. Two opt-in exceptions default off
(CLOUD_AUTH — needs email/password/secret + TLS, would otherwise fail
startup; ROUTING_STRICT — fail-closed spawning). DB_NETWORK_ISOLATED
stays on in both (coupled to the roboco_data topology).
* chore(compose): arm cloud_auth + routing_strict ON in the NAS composes
Every feature defaults ON in the NAS composes per policy — these two
were wrongly left off. Both keep the ${VAR:-true} form so the operator
controls the real runtime via .env: cloud auth needs
ROBOCO_CLOUD_AUTH_EMAIL/_PASSWORD/_SECRET + TLS set there before a boot
(else startup fails loud), and routing_strict is fail-closed. Registry
compose keeps both off.
* fix(ci): reflow board.md prose (quality gate) + document v0.17.0 env creds
The roadmap section added hard-wrapped prose that failed the markdown
prose gate; reflowed (token-invariant). Also brought .env.example
current: cloud auth (now armed — needs SECRET or startup fails), routing
strict, the X engine (panel-entered OAuth), and web research.
* fix(ci): reduce cyclomatic complexity of five wave-3 blocks (xenon gate)
The wave-3 subagents introduced C-rank functions the CI xenon gate
rejects (my per-item reviews ran ruff/mypy/pytest but not xenon):
- sandbox.janitor_sweep -> extract _list_labeled_sandboxes /
_list_live_agent_containers / _prune_grace
- x_client.fetch_mentions -> extract _parse_mention_items
- x_engine.run_cycle -> extract _process_mentions
- orchestrator._dispatch_pm_work -> extract the source-skip into a
MODULE-level _is_held_ceo_source (module, not method, so the
wholesale-mocked dispatcher unit tests exercise the real logic)
- auth/seed.ensure_seed_user -> extract _apply_seed_updates (module avg -> A)
Behavior-preserving; full suite green (11902), xenon clean.
* fix(ci): declare pyjwt + fastapi-users-db-sqlalchemy as direct deps (deptry)
The cloud-auth code imports jwt and fastapi_users_db_sqlalchemy directly
but they were only transitive deps (via fastapi-users), which deptry
(quality gate, DEP003) rejects. Declared explicitly; deptry roboco/ clean.
Missed originally because local make quality stopped at earlier gates
before reaching deptry.
* feat(x): gate mention replies behind ROBOCO_X_REPLIES_ENABLED (default off)
Per CEO decision: the X engine should only post about releases by
default. Reading mentions needs a paid X API tier, so the mention-reply
half is now a deliberate opt-in on top of release posting.
New default-off flag x_replies_enabled gates the mentions poll loop
(_x_mentions_poll_loop) and XEngine.run_cycle; release-post drafting
(the release-proposal approve hook) is unaffected and still runs when
x_engine_enabled + credentials are set. Added to FEATURE_FLAGS + the
panel card. Tests: release posting works with replies off; run_cycle +
the poll loop are no-ops with replies off.
* fix: 401 only redirects to /login when cloud auth is on; panel-token strips .env quotes
Two bugs that together dead-ended login in secure mode:
- client.ts redirected to /login on ANY 401, so a mismatched panel
token (header-trust/secure mode, cloud auth off) bounced the user to a
login page whose backend route isn't mounted -> 404. Now it probes
/auth/status (bare fetch, no interceptor re-entry) and only redirects
when cloud_auth_enabled.
- make panel-token read the .env secret with grep|cut without stripping
surrounding quotes, so a quoted ROBOCO_AGENT_AUTH_SECRET produced a
token signed with the quotes included — which never verifies against
the orchestrator (docker-compose/pydantic unquote the secret). Now
strips surrounding single/double quotes.
* fix: git-log 500 on '|' in commit message; X queue shows an empty state
- GET /api/git/log 500'd (ValueError: Invalid isoformat) when a commit
SUBJECT contained a '|' (e.g. the 'curl|sh' lockdown commit): the
fixed '|' field delimiter let the subject's pipe shift the split so
author+date collapsed into one field. Switched to \x1f (Unit
Separator), which can't appear in commit content. Regression test with
a piped subject.
- The X Post Queue returned null when empty, so there was no visible
place for the X drafts. It now renders a discoverable empty state
pointing at Settings -> X credentials.
* docs: bring docs/rag + docs/map current for v0.17.0 (waves 1-3)
Agent-facing RAG corpus and codebase map updated for every feature in
the 0.17.0 span, code-verified:
- wave 3: sandbox DB, DB network isolation, cloud auth, X engine
(+ x_replies_enabled sub-flag), board roadmap engine — new RAG
architecture pages + role/tool/config-reference updates; new symbols,
migrations 057-059, panel surfaces, and the get_agent_context
dual-path across the map slices.
- waves 1-2: A2A live view + switchboard, prompter memory
(search_past_tasks), Secretary edit access + PM-lighter scope, the
PR-gate auto-submit turn cut (ROBOCO_PR_GATE_AUTO_SUBMIT_ENABLED).
- correctness fix: api-routes-schemas.md no longer claims the A2A admin
routes are reachable by any authenticated agent — they carry a
_require_ceo gate (wave 2c).
docs/internal, _front.md deltas, and the frozen _complete_map.md
snapshot untouched.
* fix(rag): atomic upsert for indexed-doc tracking (kills e2e segfault)
The indexed-document tracking write used check-then-insert in two paths
(IndexedDocumentRepository.upsert_batch and the file-source
_upsert_doc_record). Under concurrent indexing both callers saw no row
and both inserted, so the second violated uq_indexed_doc_source and
poisoned its transaction — surfacing in CI as the intermittent
_checkin_failed SIGSEGV on the failed connection's pool checkin.
Both paths now use INSERT ... ON CONFLICT DO UPDATE against the
constraint: coalesce keeps an existing title/preview when the new value
is empty (matching the old guards) and metadata is jsonb-merged. The
batch dedupes within itself first (ON CONFLICT can't touch a row twice
in one statement). expire_all after the Core upsert keeps same-session
ORM reads consistent with the merged DB row.
---------
Co-authored-by: Renn F <rennf93@users.noreply.github.com>
This commit is contained in:
Renzo F
@@ -34,6 +34,7 @@
|
||||
- Write code or commit → devs / documenters only (`commit` is in their manifest, not yours)
|
||||
- Open or merge the master PR → the Main PM's `submit_root` opens the root→master PR and only the CEO merges it to `master`
|
||||
- Run shell git — blocked by the bash-guard hook
|
||||
- Get unrestricted task admin on the REST `PATCH /tasks/{id}` surface — cell_pm/main_pm are capped to a **content-only allowlist** (`title`, `description`, `acceptance_criteria`, `priority`; no status changes, no structural/ownership fields) — the "PM lighter" scope (`_pm_editor_scope` / `_enforce_pm_lighter_fields`, `roboco/api/routes/tasks.py`). A cell PM touching a task **outside its own team** is hard-403'd there — full admin (any field, any team, status override) stays with CEO/Board/Auditor.
|
||||
|
||||
## Task Flow (gateway verbs)
|
||||
|
||||
@@ -72,6 +73,7 @@ unclaim(task_id) / resume(task_id) / i_am_idle()
|
||||
| `roboco-flow` | `give_me_work`, `i_will_plan`, `delegate`, `submit_up`, `triage`, `unblock`, `reassign`, `complete`, `escalate_up`, `unclaim`, `resume`, `i_am_idle` |
|
||||
| `roboco-do` | `note`, `say`, `dm`, `notify`, `evidence` (no `commit`) |
|
||||
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
|
||||
| `roboco-search` | `web_search`, `web_fetch` (only when `ROBOCO_RESEARCH_ENABLED`, default on) |
|
||||
| `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` |
|
||||
| `roboco-docs` | project doc file ops |
|
||||
|
||||
@@ -154,6 +156,8 @@ When every subtask of your cell-scoped parent is terminal (each leaf PR merged i
|
||||
|
||||
Re-`submit_up` is refused if the assembled PR is **unchanged** since the last `pr_fail` (no new commits on it) — it stops a re-submit-the-same-PR loop. Fix the issues and commit before re-submitting.
|
||||
|
||||
**You may never even see this turn.** When every subtask is terminal, the orchestrator's closure dispatcher first tries `_try_auto_submit`: if `ROBOCO_PR_GATE_AUTO_SUBMIT_ENABLED` (default on) and the parent has a branch + project, it runs the real `submit_up` system-side as you, skipping your spawn for that turn — the submit's substance (freshness rebase, integrity check, PR open) is deterministic gate code, not judgment. A gate rejection (freshness/integrity) falls back to spawning you for the classic closure turn instead. Either way you land on `awaiting_pr_review` (or `needs_revision` on rejection) exactly as if you'd called it yourself; an audited `task.auto_submitted` event marks the cut.
|
||||
|
||||
You merge your own cell→root PR — the Main PM does **not** merge your cell branch. The Main PM owns the **root** task: once every cell's parent is terminal, it runs the same gate one level up (`submit_root` → main reviewer → escalate to CEO) and only the CEO merges to `master`. You never open or merge a master PR yourself.
|
||||
|
||||
`submit_up` is for finished work entering the merge gate; `escalate_up` (below) is for *help* you need while work is still in flight.
|
||||
|
||||
@@ -35,6 +35,15 @@ When a Main PM or Board member escalates a major task via `escalate_to_ceo`, it
|
||||
|
||||
Both are panel actions; the agent that escalated simply idles until the CEO decides.
|
||||
|
||||
### X posts and roadmap items (panel-only, not gateway verbs)
|
||||
|
||||
Two more CEO-only approval queues, both plain REST endpoints on the orchestrator (not lifecycle transitions, not agent-callable verbs):
|
||||
|
||||
- **X (Twitter) posts** — `GET/POST /api/x/posts{,/{id}/approve,/reject}`. Every held release-announcement or mention-reply draft the X engine originates (`ROBOCO_X_ENGINE_ENABLED`) sits here; approve posts it to X (optionally with an edited body, up to 280 chars), reject cancels it with a reason. Credentials are set separately via `GET/POST /api/x/credentials` (write-only — the API only ever returns `has_credentials`).
|
||||
- **Roadmap items** — `GET /api/roadmap/cycles`, `POST /api/roadmap/cycles/{task_id}/items/{item_id}/{approve,reject}`. Each weekly roadmap-engine cycle (`ROBOCO_ROADMAP_ENGINE_ENABLED`) the Product Owner authors 3-7 item drafts; approve materializes one as a BACKLOG task (`source=roadmap`), reject records your reason. Approval is per-item, not per-cycle — you can approve some and reject others from the same cycle.
|
||||
|
||||
Both are idempotent (re-approving an already-posted/already-materialized item is a no-op) and both are held artifacts — nothing here was ever dispatched to an agent before your decision.
|
||||
|
||||
## Escalation
|
||||
|
||||
The CEO is the final escalation target:
|
||||
|
||||
@@ -19,7 +19,9 @@
|
||||
- Escalate tasks to the CEO via `escalate_to_ceo(task_id, reason)`
|
||||
- Communicate: `say` (channel), `dm` (A2A), `notify` (ack-required signal)
|
||||
- Open strategic sessions via `open_session`
|
||||
- Propose a product via `pitch(title, slug, problem, proposed_solution, target_cells)` — queues for CEO approval, then auto-provisions
|
||||
- Read project docs via `roboco_docs_read` / `roboco_docs_list`
|
||||
- Research the market via `web_search` / `web_fetch` (when `ROBOCO_RESEARCH_ENABLED`)
|
||||
- Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`
|
||||
|
||||
## What You CANNOT Do
|
||||
@@ -35,12 +37,17 @@
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `triage`, `escalate_to_ceo`, `i_am_idle` |
|
||||
| `roboco-do` | `note`, `say`, `dm`, `notify`, `evidence`, `open_session` |
|
||||
| `roboco-do` | `note`, `pitch`, `say`, `dm`, `notify`, `evidence`, `open_session` |
|
||||
| `roboco-docs` | `roboco_docs_read`, `roboco_docs_list` |
|
||||
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
|
||||
| `roboco-search` | `web_search`, `web_fetch` (only when `ROBOCO_RESEARCH_ENABLED`) |
|
||||
| `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` |
|
||||
|
||||
Your flow surface is deliberately narrow: the Board steers and approves, it does not claim, create, or complete tasks.
|
||||
Your flow surface is deliberately narrow: the Board steers and approves, it does not claim, create, or complete tasks. Unlike the Product Owner, you do **not** get `propose_roadmap` — that tool is Product-Owner-only.
|
||||
|
||||
## X (Twitter) Engine — Not a New Tool for You
|
||||
|
||||
The X engine (`ROBOCO_X_ENGINE_ENABLED`, default off) drafts release-announcement and mention-reply posts for the company's X account, in your marketing voice — but it does **not** add anything to your tool surface above. Drafting is done by a direct local-model call from `XEngine` (`roboco/services/x_engine.py`), not by spawning you as an agent; every draft lands as a held task **owned by the Secretary** (`assigned_to=secretary-1`, `team=main_pm`), never assigned to you. The CEO reviews and approves/rejects each draft in the panel (`GET/POST /api/x/posts{,/{id}/approve,/reject}`, CEO-only) — nothing posts without that explicit per-post approval. If you want to review or influence a draft's content, ask the CEO directly (via `dm` or the escalation chain below) rather than expecting a task in your queue.
|
||||
|
||||
## Escalation
|
||||
|
||||
|
||||
@@ -84,10 +84,15 @@ channels() # discover the pm-all channel, then read its history
|
||||
| `roboco-do` | `note`, `say`, `dm`, `notify`, `evidence`, `open_session`, `link_session`, `pr_update` |
|
||||
| `roboco-docs` | `roboco_docs_write`, `roboco_docs_read`, `roboco_docs_list` |
|
||||
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
|
||||
| `roboco-search` | `web_search`, `web_fetch` (only when `ROBOCO_RESEARCH_ENABLED`, default on) |
|
||||
| `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` |
|
||||
|
||||
Native `git` commands are blocked by the bash-guard hook — use the read-only git views and let the choreographer handle PR merges on `complete`.
|
||||
|
||||
## Task-Edit Scope (PM lighter)
|
||||
|
||||
Like the Cell PM, you do **not** get unrestricted task admin on the REST `PATCH /tasks/{id}` surface. `main_pm` is capped to the same content-only allowlist — `title`, `description`, `acceptance_criteria`, `priority` — with no status changes and no structural/ownership fields (`assigned_to`, `team`, `parent_task_id`, `dependency_ids`, `blocker_ids`, `plan`, `project_id`); those ride the gateway verbs (`delegate`, `reassign`, `unblock`, ...), not this PATCH surface. Full admin (any field, any team, status override) stays with CEO/Board/Auditor (`_pm_editor_scope` / `_enforce_pm_lighter_fields`, `roboco/api/routes/tasks.py`).
|
||||
|
||||
## Projects and Git Tokens
|
||||
|
||||
Registering repositories and storing git tokens is **not** an agent action — it is done by a human in the panel (project settings). Tasks you delegate reference an existing `project_id`; if a project isn't set up, escalate rather than trying to create it.
|
||||
@@ -112,6 +117,7 @@ master ← feature/main_pm/{root} ← feature/{cell}/{root}/{cell-pm} ←
|
||||
|
||||
- A cell PM's `complete` merges a leaf PR into its cell branch; after the cell gate, its `complete` merges the cell→root PR into your root branch. You do not merge cell branches.
|
||||
- Once every cell's parent is terminal, **`submit_root(root_task_id, notes)`** opens the root→master PR and enters the in-path gate (`awaiting_pr_review`). The **main PR reviewer** checks the assembled root diff: `pr_pass` → `awaiting_pm_review`; `pr_fail` → `needs_revision` (owned by you, fix + re-`submit_root`). The reviewer's verdict + issues are carried in your task handoff, and re-`submit_root` is refused if the root PR is **unchanged** since the last `pr_fail` — fix and commit before re-submitting.
|
||||
- **The system may call `submit_root` for you.** When every cell's parent is terminal, the orchestrator's closure dispatcher tries `_try_auto_submit` first: with `ROBOCO_PR_GATE_AUTO_SUBMIT_ENABLED` (default on) and a branch + project on the root, it runs `submit_root` system-side as you — skipping your spawn for that turn, since the submit's substance is deterministic gate code, not judgment. A gate rejection (freshness/integrity) falls back to spawning you for the classic closure turn. Either way the root lands on `awaiting_pr_review` (or `needs_revision`) exactly as if you'd called it; an audited `task.auto_submitted` event marks the cut. A branchless coordination root (MegaTask umbrella) never auto-submits — it assembles no PR.
|
||||
- After `pr_pass`, `complete(root_task_id, notes)` escalates the root to the CEO (`awaiting_ceo_approval`) — it does **not** merge. A branchless coordination root (product fan-out, no repo) skips the gate and `complete` escalates directly.
|
||||
- The CEO approves and merges the root→master PR from the panel. Only the CEO ever merges to `master`.
|
||||
|
||||
|
||||
@@ -20,7 +20,10 @@
|
||||
- Escalate tasks to the CEO via `escalate_to_ceo(task_id, reason)`
|
||||
- Communicate: `say` (channel), `dm` (A2A), `notify` (ack-required signal)
|
||||
- Open strategic sessions via `open_session`
|
||||
- Propose a product via `pitch(title, slug, problem, proposed_solution, target_cells)` — queues for CEO approval, then auto-provisions
|
||||
- Author the weekly roadmap-engine exploration cycle via `propose_roadmap(cycle_goal, items)` — see "Roadmap Engine" below
|
||||
- Read project docs via `roboco_docs_read` / `roboco_docs_list`
|
||||
- Research the market via `web_search` / `web_fetch` (when `ROBOCO_RESEARCH_ENABLED`)
|
||||
- Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`
|
||||
|
||||
## What You CANNOT Do
|
||||
@@ -36,12 +39,37 @@
|
||||
| MCP server | Verbs you can call |
|
||||
|-----------------------|--------------------|
|
||||
| `roboco-flow` | `triage`, `escalate_to_ceo`, `i_am_idle` |
|
||||
| `roboco-do` | `note`, `say`, `dm`, `notify`, `evidence`, `open_session` |
|
||||
| `roboco-do` | `note`, `pitch`, `propose_roadmap`, `say`, `dm`, `notify`, `evidence`, `open_session` |
|
||||
| `roboco-docs` | `roboco_docs_read`, `roboco_docs_list` |
|
||||
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
|
||||
| `roboco-search` | `web_search`, `web_fetch` (only when `ROBOCO_RESEARCH_ENABLED`) |
|
||||
| `roboco-optimal` | `roboco_ask_mentor`, `roboco_kb_search` |
|
||||
|
||||
Your flow surface is deliberately narrow: the Board steers and approves, it does not claim, create, or complete tasks.
|
||||
Your flow surface is deliberately narrow: the Board steers and approves, it does not claim, create, or complete tasks. `propose_roadmap` is a content verb, not a flow verb — you author the roadmap cycle without claiming a delivery task.
|
||||
|
||||
## Roadmap Engine
|
||||
|
||||
Weekly (`ROBOCO_ROADMAP_ENGINE_ENABLED`, default off), the roadmap engine opens ONE held exploration task assigned to you (`source=board_roadmap`, PENDING, `confirmed_by_human=False`). When spawned for it, explore the company's projects, charter, recent releases, and metrics, then call `propose_roadmap(cycle_goal, items)` **exactly once**:
|
||||
|
||||
```python
|
||||
propose_roadmap(
|
||||
cycle_goal="Close the mobile-experience gap before Q3",
|
||||
items=[
|
||||
{
|
||||
"title": "...",
|
||||
"description": "...",
|
||||
"acceptance_criteria": ["..."],
|
||||
"project_slug": "roboco-api",
|
||||
"team": "backend", # backend | frontend | ux_ui
|
||||
"priority": 2,
|
||||
"rationale": "why this, why now",
|
||||
},
|
||||
# 3-7 items total
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
The CEO then reviews and approves/rejects each item **individually** in the roadmap queue (`GET/POST /api/roadmap/cycles/{task_id}/items/{item_id}/{approve,reject}`, CEO-only). An approved item materializes as a real BACKLOG task (`source=roadmap`) — nothing here auto-starts it; it waits for normal PM activation like any other backlog task. One open cycle at a time: the engine won't originate a new exploration task while one is still awaiting your authoring or the CEO's per-item decisions.
|
||||
|
||||
## Escalation
|
||||
|
||||
|
||||
@@ -24,7 +24,9 @@ It runs in its own `agent-prompter` container as a persistent `ClaudeSDKClient`
|
||||
|
||||
- Read and search the codebase: `Read`, `Grep`, `Glob`
|
||||
- Spawn read-only sub-explorations to ground the draft (`Task`)
|
||||
- Check prior art mid-conversation via **`search_past_tasks(query, limit=8)`** — searches past tasks by title/description/id-prefix and returns up to 10 compact rows (short id, title, status, team, date), so you can answer "have we done something like this before?" or cite a predecessor in a new draft's description
|
||||
- Produce the reviewable draft by calling **`propose_draft`** — the canonical "the spec is ready" signal; the orchestrator turns it into the draft card the human approves
|
||||
- Propose a **MegaTask** — several sequenced task drafts at once — by calling **`propose_batch(drafts, title)`** instead of `propose_draft` when the CEO asks for multiple tasks across the scoped repos; each draft carries a collision surface (`intends_to_touch`, `adds_migration`, `touches_shared`, `depends_on`) the sequencing analyzer uses to order them into conflict-free waves
|
||||
- Journal privately via `note(...)` and cite sources via `evidence(...)`
|
||||
|
||||
## What You CANNOT Do
|
||||
@@ -46,12 +48,16 @@ Interview first, draft second. A good draft follows the **task spec standard**:
|
||||
|
||||
When the spec is ready, call `propose_draft` with the structured draft. The human reviews the card and decides whether to launch it, and to whom.
|
||||
|
||||
## Ambient Task History (auto-injected, no tool call)
|
||||
|
||||
Every intake conversation scoped to a project is automatically given a **task-history digest** — a chronological "## Task History" block listing that project's most recent tasks (short id, title, status, date), one section per project for a MegaTask's multi-project scope. It's rendered by `history_digest_layer` (`roboco/services/prompter.py`, backed by `TaskService.list_recent_for_project`) and injected ambiently at session start; you don't call anything for it. Use `search_past_tasks` (above) when you need a keyword hit the digest's recency window doesn't cover.
|
||||
|
||||
## Tool Surface (locked-down SDK session)
|
||||
|
||||
| Source | Tools |
|
||||
|--------|-------|
|
||||
| Base (read-only) | `Read`, `Grep`, `Glob`, `Task` |
|
||||
| Intake MCP | `propose_draft` (emit the reviewable draft) |
|
||||
| Intake MCP | `propose_draft` (emit the reviewable draft), `search_past_tasks` (prior-art search), `propose_batch` (MegaTask — several sequenced drafts at once) |
|
||||
| `roboco-do` (gateway) | `note`, `evidence` |
|
||||
|
||||
The session is isolated: a hard tool allowlist (no host settings, no extra MCP servers), `permission_mode="dontAsk"`, and no outward-comms surface. Anything not listed above is denied.
|
||||
|
||||
@@ -23,7 +23,7 @@ It runs in its own `agent-secretary` container, reusing the Intake chat machiner
|
||||
|
||||
- Read the codebase: `Read`, `Grep`, `Glob`
|
||||
- Read a compact company snapshot via **`read_company_state`** — the charter (goals), task counts by status, pending pitches, and any directives already awaiting the CEO's confirmation
|
||||
- Read one task's detail via **`read_task`**
|
||||
- Read one task's **full detail** via **`read_task(task_id)`** — Secretary FULL task access: beyond identity/status/description this also carries acceptance criteria, plan, bounded recent `progress_updates`, dev/qa/auditor/pr-reviewer/doc notes, and the branch/PR reference
|
||||
- Act on the CEO's command via **`submit_directive`** (see below)
|
||||
|
||||
## What You CANNOT Do
|
||||
@@ -42,12 +42,34 @@ It runs in its own `agent-secretary` container, reusing the Intake chat machiner
|
||||
|------|---------|--------------|
|
||||
| `relay_message` | `channel`, `text` | Runs directly |
|
||||
| `update_charter` | `charter` | Queued for the CEO |
|
||||
| `control_task` | `task_id`, `action` (`start`/`cancel`/`override`), `status?` | Queued for the CEO |
|
||||
| `control_task` | `task_id`, `action` (`start`/`cancel`/`override`/`edit`), `status?` (for `override`), `fields?` (for `edit`) | Queued for the CEO |
|
||||
| `approve_pitch` | `pitch_id`, `notes?` | Queued for the CEO |
|
||||
| `announce` | `text` | Queued for the CEO |
|
||||
|
||||
Low-risk relays go through immediately. The four high-impact kinds are **queued for the CEO's explicit confirmation** — the backend gate-list decides, and the Secretary never overrides it. Tell the CEO when a directive has been queued, and why.
|
||||
|
||||
### `control_task action="edit"` — Secretary FULL task access
|
||||
|
||||
`edit` applies a content edit + optional reassignment on the CEO's confirmed command, via `fields={...}`:
|
||||
|
||||
- Editable fields (`_EDITABLE_TASK_FIELDS` in `roboco/services/secretary.py`): `title`, `description`, `acceptance_criteria`, `priority`, `team`, `estimated_complexity`, `nature`, `assigned_to`. Any other key is rejected outright — `status` is never set through `edit` (use `override`/`start`/`cancel` instead), and git fields (branch/PR) are never editable at all.
|
||||
- `assigned_to` may be a UUID or an agent slug (e.g. `"be-dev-1"`), and is **claim-aware**: reassigning a task that is `claimed`/`in_progress` reseeds the new assignee's heartbeat (`reassign_active_claim`) instead of a naive field set, so they aren't immediately stale to the reaper; anything else routes through the general `reassign` (or unassigns on `assigned_to=null`).
|
||||
|
||||
```python
|
||||
submit_directive(
|
||||
kind="control_task",
|
||||
payload={
|
||||
"task_id": "<task>",
|
||||
"action": "edit",
|
||||
"fields": {"priority": 1, "assigned_to": "be-dev-2"},
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
### Resolving a task by name
|
||||
|
||||
The CEO refers to tasks by **name**, not UUID. The backend exposes `GET /secretary/tasks?q=` (Secretary/CEO-gated; title/description/id-prefix search, capped at 50 rows) precisely for that name→id resolution — but as of this writing it isn't wired to a Secretary tool in either runtime (only `read_company_state` / `read_task` / `submit_directive` are). Until it is, resolve a name the CEO mentions from `read_company_state`'s task counts / your own conversation context, or ask the CEO to confirm the short id before you `control_task` or `read_task` it.
|
||||
|
||||
## Tool Surface (locked-down SDK session)
|
||||
|
||||
| Source | Tools |
|
||||
|
||||
Reference in New Issue
Block a user