From c0abca90d8e7a5e6cf504dc07fe32bcdef0f26be Mon Sep 17 00:00:00 2001 From: gsxdsm Date: Sun, 5 Jul 2026 16:51:05 -0700 Subject: [PATCH] FN-7598: add planner-oversight discovery pointers to README and docs hub MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docs-only change adding front-door discovery for the already-shipped planner-oversight feature (FN-7508 โ†’ FN-7583), which previously had no entry point outside internal reference docs. - Add a README.md feature table row and a new "Planner oversight" section describing oversight levels (off/observe/steer/autonomous) and the always-on human-confirmation gate for merge/PR and destructive actions, linking to Settings Reference and Dashboard Guide - Add a README.md capabilities bullet cross-linking the new section - Add a docs/README.md hub row pointing to Settings Reference, Dashboard Guide, and Architecture for planner oversight, and extend the 'power user' reading path - Add a one-line pointer in docs/getting-started.md workflow section noting per-task/workflow oversight controls Files changed: README.md | 11 +++++++++++ docs/README.md | 9 ++++++--- docs/getting-started.md | 3 +++ 3 files changed, 20 insertions(+), 3 deletions(-) Fusion-Task-Id: FN-7598 Fusion-Task-Lineage: 8141b44c-f007-45c0-a057-f4eeb34ae8d4 Co-authored-by: Fusion (runfusion.ai) --- README.md | 11 +++++++++++ docs/README.md | 9 ++++++--- docs/getting-started.md | 3 +++ 3 files changed, 20 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7092cce277..b75e16bd9c 100644 --- a/README.md +++ b/README.md @@ -136,6 +136,7 @@ Every task shows its plan, its reviews, its diffs, and its file changes in real |---|---| | ๐Ÿง  **AI planning** | Describe a task in plain language. Planning agents turn it into a `PROMPT.md` plan with steps, file scope, and acceptance criteria. | | ๐Ÿ” **Selectable workflows** | Built-ins cover coding, quick fixes, review-heavy work, stepwise execution, plugin-gated Compound Engineering, and PR lifecycle fragments. Pick a workflow per task or author custom ones in the [Workflow Editor](./docs/workflow-editor.md). | +| ๐Ÿ›ก๏ธ **Planner oversight** | Per-task or per-workflow oversight level (`off` / `observe` / `steer` / `autonomous`) governs how closely a planner overseer watches and intervenes โ€” merge/PR and destructive actions always require explicit human confirmation. See [Settings Reference](./docs/settings-reference.md#workflow-settings) and [Dashboard Guide](./docs/dashboard-guide.md). | | ๐ŸŒณ **Worktree isolation** | Each task runs in its own branch and worktree (`fusion/{task-id}`). Parallel tasks. Zero conflicts. Optional [worktrunk](https://github.com/max-sixty/worktrunk) delegation via [`worktrunk.enabled`](./docs/settings-reference.md#worktree-backend-settings) (see [WorktreeBackend abstraction](./docs/architecture.md#worktreebackend-abstraction)). | | โšก **Smart merge controls** | Passing every gate? Fusion squash-merges and moves on. Opt into manual approval anywhere, inherit the live global auto-merge default, or set explicit per-task auto/manual overrides. | | ๐Ÿ›ฐ๏ธ **Multi-node mesh** | Laptop, Mac mini, Linux server, cloud VM, phone โ€” all synced. Desktop, mobile, web. | @@ -385,6 +386,15 @@ Fusion workflows define how a task moves from idea to delivery. The default codi Read [Workflow Steps](./docs/workflow-steps.md) for runtime semantics, built-in workflow behavior, and workflow-step templates; read [Workflow Editor](./docs/workflow-editor.md) for the dashboard authoring guide. + + +### Planner oversight + +Each workflow (and optionally each task) can set a **planner oversight** level โ€” `off`, `observe`, `steer`, or `autonomous` (default) โ€” controlling how closely a planner overseer watches and intervenes in that task's execution. Even at `autonomous`, merge/PR progression and any destructive or external-service side effect always require an explicit, recorded human confirmation before they run. Notification verbosity is controlled separately. Set the default in the **Workflow Editor โ†’ Values** tab, or override per task from the New Task dialog / Task Detail edit form. Read [Settings Reference](./docs/settings-reference.md#workflow-settings) for the full setting semantics and [Dashboard Guide](./docs/dashboard-guide.md) for the UI controls. + --- ## Multi-node. One board. Every platform. @@ -504,6 +514,7 @@ npx companies.sh add paperclipai/companies/gstack - **Visual Workflow Editor** โ€” Inspect read-only built-ins, duplicate/customize workflows, and edit graph nodes, columns, task fields, typed settings, and per-project values ([Workflow Editor](./docs/workflow-editor.md)) - **Workflow Steps** โ€” Configurable quality gates (pre-merge: blocks merge; post-merge: informational), plus workflow-declared optional steps such as opt-in [Browser Verification](./docs/workflow-steps.md#workflow-declared-optional-steps) - **Workflow-native policy** โ€” Fast-mode planning (`leanPlanning` / `autoApproveSpec`), typed triage thresholds, review/approval, step execution, and model/fallback lanes are workflow settings, not hard-coded engine constants ([Settings Reference](./docs/settings-reference.md#workflow-native-triage-policy-settings); [workflow settings](./docs/settings-reference.md#workflow-settings)) +- **Planner oversight** โ€” Workflow-native `plannerOversightLevel` (`off`/`observe`/`steer`/`autonomous`), with an optional per-task override and a separate notification-verbosity setting; merge/PR progression and destructive actions always require explicit human confirmation, even at `autonomous` ([overview](#planner-oversight); [Settings Reference](./docs/settings-reference.md#workflow-settings)) - **GitHub + PR lifecycle** โ€” Import issues, create PRs, display real-time PR/issue badges, and use workflow-mode PR lifecycle graph fragments where enabled - **Dashboard** โ€” Real-time kanban/list/graph views, agent management, terminal, git manager, mission planner, chat, workflow editor, custom provider setup, and one-click update action - **Missions** โ€” Hierarchical planning (Mission โ†’ Milestone โ†’ Slice โ†’ Feature โ†’ Task) with autopilot, validation contracts, fix-feature retries, mission-goal linking, and blocked-handoff semantics diff --git a/docs/README.md b/docs/README.md index 9b0c003a59..28d5bfba19 100644 --- a/docs/README.md +++ b/docs/README.md @@ -43,11 +43,14 @@ For a full walkthrough (installation, onboarding, first task, and daily workflow | [Multi-Project](./multi-project.md) | Central registry architecture, project management, isolation modes, and migration paths | ### Configuration & Agents -| Guide | Description | -|---|---| + | [Settings Reference](./settings-reference.md) | Global/project settings, workflow setting values, model/fallback lane hierarchy, defaults, and API endpoints | | [MCP](./mcp.md) | Model Context Protocol server configuration, secret references, validation, CLI, dashboard, and import/export workflows | | [Agents](./agents.md) | Agent management, presets, prompts, heartbeat behavior, spawning, and mailbox workflows | +| Planner Oversight (see [Settings Reference](./settings-reference.md#workflow-settings), [Dashboard Guide](./dashboard-guide.md), [Architecture](./architecture.md)) | Workflow-native oversight levels (`off`/`observe`/`steer`/`autonomous`), per-task overrides, notification verbosity, the human-confirmation gate on merge/PR and destructive actions, and the Task Detail overseer controls/Intervention Timeline | ### Architecture & Development | Guide | Description | @@ -151,5 +154,5 @@ FN-7088 links previously-unlinked first-class testing and baseline docs here so - **New user:** Getting Started โ†’ Dashboard Guide โ†’ Task Management - **Workflow author:** Dashboard Guide โ†’ Workflow Editor โ†’ Workflow Steps โ†’ Settings Reference -- **Power user / automation owner:** Settings Reference โ†’ Workflow Steps โ†’ Agents +- **Power user / automation owner:** Settings Reference โ†’ Workflow Steps โ†’ Agents โ†’ Planner Oversight (Settings Reference ยง Workflow Settings) - **Maintainer / contributor:** Architecture โ†’ Multi-Project โ†’ Contributing diff --git a/docs/getting-started.md b/docs/getting-started.md index 0436bb6002..74bd81d7ba 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -137,6 +137,9 @@ Most tasks can use the default **Coding** workflow. When the workflow selector i Built-ins include task-selectable Coding, Legacy coding, Quick fix, Review-heavy, plugin-gated Compound engineering, Coding (per-step review), and Design workflows, plus PR lifecycle fragments for workflow authors. For the full catalog and runtime behavior, see [Workflow Steps](./workflow-steps.md#workflow-overview). To inspect built-ins or author custom workflows, open the dashboard [Workflow Editor](./workflow-editor.md). + +Workflows (and individual tasks) also have a **Planner oversight** level (`off`/`observe`/`steer`/`autonomous`) that controls how closely a planner overseer watches and can intervene; see [Settings Reference](./settings-reference.md#workflow-settings) for the setting semantics and [Dashboard Guide](./dashboard-guide.md) for the UI controls. + ## Understand the Task Lifecycle Fusion uses six default lifecycle columns: