@humwick/server 0.0.0-stage → 0.130.0

package/docs/guides/tools-tasks.md

@@ -0,0 +1,235 @@
+---
+title: Relay tool reference — tasks
+summary: Tool behavior, constraints and parameter details for tasks.
+tags: [tools, mcp, tasks]
+---
+
+Read these details when a tool's compact schema is not enough. Names and input contracts are unchanged.
+
+## relay_backlog
+
+Query the per-project prioritized backlog: deliverable Tasks awaiting dispatch, ordered by priority then recency. Filter by project/repo, priority, tags (AND), parent task, execution status, and created/updated time ranges; free-text `search` matches title/intent. Sort priority|updated|created (default priority). Paginate with maxItems (hard cap 200) + offset. Projects lean by default; pass verbosity brief|verbose. `state` defaults to `backlog` (un-promoted); use `promoted` or `all` to include dispatched items.
+
+- `search`: substring match over title/intent
+- `repo`: owner/repo scope
+- `tags`: all listed tags must be present (AND)
+- `parentTaskId`: Task id (TNNNN accepted).
+- `createdAfter`: epoch ms; created_at >= this
+- `createdBefore`: epoch ms; created_at <= this
+- `updatedAfter`: epoch ms; updated_at >= this
+- `updatedBefore`: epoch ms; updated_at <= this
+- `state`: default backlog
+- `sort`: default priority (priority desc, updated desc)
+- `verbosity`: default = lean card; brief = id/title/priority/status; verbose = full row
+
+## relay_backlog_promote
+
+Promote a backlog Task to dispatch: flip it backlog→active and run the existing dispatch path (provider/model/effort decision + optional dependent review Task). Only a task currently in the backlog can be promoted. Optionally override the dispatch work-shape and pin a target; does NOT spawn (that stays with the coordinator / #838).
+
+- `pin`: Explicit per-case override for the dispatch target; any field set wins over the policy-derived target.
+- `createReview`: create the dependent review Task when the auto-review threshold is met. Default true.
+
+## relay_release_readiness
+
+Report landed-on-main deliverable Tasks not yet deployed/released, anchored to the last release tag on git (not the Task DB backlog). Returns a lean summary with a small task preview by default; pass `limit` to page through the full `totalTasks` count.
+
+- `limit`: Explicit page size for the full task list; omit for a lean default preview.
+
+## relay_task_add_dependency
+
+Add a task→task dependency edge (taskId depends on dependsOnTaskId). Rejects cycles transactionally.
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+- `dependsOnTaskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+
+## relay_task_add_ref
+
+Attach a ref to a Task: an issue (linked via issue_associations, hydrated into task-bound spawns), a branch, and/or a commit. Errors rather than silently no-opping when no ref is supplied.
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+- `issue`: #n, owner/repo#n, GitHub URL, or issue_<id>. Aliases accepted: issueRef, ref, refs, issues, externalKey, issueNumber, issueRefId.
+- `relation`: Issue relation: delivers authorizes auto-close at land; references only links/hydrates the spec. Omitted relations resolve from the current Task type at land: delivers for build/ui/refactor/debug/mechanical (or an omitted type with a build-like bound profile), references for research/design (use research), review and ops. Unset type derives from the bound profile: software-design, reviewer, isolated-research and ops-assistant reference; other profiles default to build. Inferred refs always store references. Applies to every issue in this call; re-add with a relation to change it, or omit relation to preserve an existing explicit one.
+- `defaultRepo`: owner/repo for a bare #n; defaults to the Task's repo, else your own project's repo
+
+## relay_task_assign_agent
+
+Record an agent as the Task's execution owner (writes owner_agent_id + an attribution event; never the claim lease).
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+
+## relay_task_close_bridge
+
+Read the close-bridge projection for a Task: for each linked issue, whether #482/#474 already closed it on land (commit, land key, when). Closes the 'I couldn't tell if it was already closed' gap by surfacing the canonical issue-lifecycle ledger — no duplicated state.
+
+## relay_task_comment
+
+Comment on a Task — writes a structured comment THROUGH to the linked GitHub issue (GitHub is the backing store for human discussion; the Task is the lens). Execution telemetry NEVER writes through; this is for discussion only. Requires the Task to have a linked GitHub issue. Optional clientId dedupes a re-delivered comment.
+
+- `body`: the comment text (Markdown)
+- `clientId`: idempotency key — a re-delivered comment with the same key posts once
+
+## relay_task_confirm_carry
+
+Confirm a #1456 carry-pending Task: assert the delivered change discarded by a moved-base protected-tip revert was carried onto the current base. Removes ONLY the carry-pending blocker (preserves any other blockers); if the branch already landed, pass `commit` to advance the Task to landed-on-main. The ONLY way to clear a carry-pending block — nothing auto-clears it. PRIVILEGED: only the task's coordinator or an assigned steward may call this (not the branch worker); ordinary task:write is not sufficient. Known limitation (#1456 MVP): passing `commit` completes the land only — it does NOT re-run the full task lifecycle (issue-close/reap/milestone); the confirmer handles those manually. Automatic host-side tree-level carry verification is tracked in #1458.
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+
+## relay_task_create
+
+Create a durable deliverable Task (#834). Owns execution telemetry (status, stage, gates, branch, commits, deps); references GitHub issue(s) for intent/spec. Optionally seed issue refs and dependencies. Returns id, status, issue refs and review-hold state; pass verbose:true for the full Task.
+
+- `label`: alias for title; concise task label
+- `intent`: original prompt / why this task exists
+- `complexity`: coarse task complexity; defaults to moderate
+- `context`: optional context needed to understand or execute the task; hydrated (fenced as untrusted data, trimmed) into a task-bound spawn's first-turn brief, so key facts need no follow-up message
+- `terminalStage`: Override repo terminal: defaults to deployed for the CD-watched repo, landed-on-main otherwise. Explicit doneWhen lifecycle tokens take precedence.
+- `doneWhen`: exit predicate / acceptance for execution
+- `repo`: owner/repo for the task's project/repository
+- `branch`: optional branch ref to seed on the task
+- `issueRefs`: Issue(s) this Task delivers or references (see relation): #n, owner/repo#n, GitHub URL, or issue_<id>. Linked issues are hydrated into a task-bound spawn's first-turn brief, so pass the ref instead of pasting the spec. Aliases accepted: refs, issues, issue, issueRef, externalKey, issueNumber. A bare #n resolves against defaultRepo, else the Task's repo, else your own project's repo.
+- `relation`: Issue relation: delivers authorizes auto-close at land; references only links/hydrates the spec. Omitted relations resolve from the current Task type at land: delivers for build/ui/refactor/debug/mechanical (or an omitted type with a build-like bound profile), references for research/design (use research), review and ops. Unset type derives from the bound profile: software-design, reviewer, isolated-research and ops-assistant reference; other profiles default to build. Inferred refs always store references. Applies to every issue in this call; re-add with a relation to change it, or omit relation to preserve an existing explicit one.
+- `defaultRepo`: owner/repo for bare #n issue refs
+- `idempotencyKey`: Stable client-generated key; reuse after an indeterminate create to reconcile without duplicating the Task.
+- `verbose`: Return the full Task instead of the lean creation receipt.
+- `backlog`: #1535 WS3 — file directly into the prioritized backlog (queryable via relay_backlog) until promoted to dispatch
+
+## relay_task_deliver
+
+Submit a structured Delivery Result for a durable Task. Writes a typed deliverable event to the Task thread before any side effect and returns the Task's currently linked issues for hand-off visibility. disposition:'complete' requires passing the 'test' gate only when the workspace diff (computed on the workspace's owning host) touches code/test/config paths; empty/docs-only diffs record a skipped 'test' gate and can still land. Any other self-reported gate must not be failing. IMPORTANT — idempotencyKey is REQUIRED for disposition:'complete' deliveries that arm a landing (land-type tasks; provide a stable key so a retry cannot double-land), and recommended for every delivery; omitting it on a landing complete is rejected.
+
+- `taskId`: Task id. Optional when the caller is bound to exactly one Task. TNNNN form (e.g. "T4409") accepted.
+- `reason`: Required for blocked/failed deliveries.
+- `blockedBy`: Required for blocked deliveries; records the blocker set on the Task.
+- `outputs`: Structured workflow role outputs, validated by the action output schema.
+- `workspaceId`: Defaults to the caller's isolated workspace.
+- `allowStrandedBranches`: Explicitly proceed after reviewing the named stranded-cycle branch warning.
+- `workspace`: The caller's own workspace descriptor (from HUMWICK_WORKSPACE_JSON). Injected by the runner; used only to self-heal a missing workspace registration so a completed delivery isn't stranded on a 404.
+- `idempotencyKey`: Dedupes retry delivery and prevents double-land on replay. REQUIRED for a complete delivery that requests landing — a landing complete without it is rejected with 'complete landing delivery requires a nonempty stable idempotencyKey'; reuse the SAME key when retrying a lost-acknowledgement delivery.
+
+## relay_task_dispatch
+
+Auto-spawn a builder for a Task: map its work-shape ({complexity,type,contextFootprint,criticality}) + live quota/bands onto a concrete spawn (provider/model/effort) with a rationale, then ACTUALLY SPAWN that agent bound to the taskId through the same shared spawn path as relay_spawn_agent (#2522). Returns the relay_spawn_agent receipt ({ok,status,orchestratorId,provider,agentId,spawnRequestId,taskId}) plus the decision/rationale for observability. Idempotent retry follows the relay_spawn_agent contract: pass the SAME caller-supplied spawnRequestId to dedupe onto the existing spawn; when omitted a fresh unique id is generated and a retried dispatch may spawn again. Without a taskId it is a plan-only routing preview (no spawn). When the policy's auto-review threshold is met it creates a dependent review Task (opt out with createReview:false).
+
+- `pin`: Explicit per-case override; any field set wins over the policy-derived target.
+- `createReview`: When a taskId is given and the auto-review threshold is met, create the dependent review Task. Default true.
+- `profile`: Agent profile for the spawned worker (env, instructions, permissions, MCP/skills). Omit for the spawn default. Excludes role.
+- `role`: Project role (.agent-relay/roles/<name>.md at the project's default-branch commit; needs a taskId and excludes profile). The Task's work-shape still picks the provider and model; the role's own dispatch shape is only the fallback when the Task has none, and the role's model pin wins over the dispatcher's.
+- `label`: Label for the spawned worker; defaults to `task-<id>: <title>`.
+- `steer`: One-line actionable instruction layered over the hydrated Task context — the spawned agent's first-turn steer.
+- `cwd`: Working directory for the spawned agent. Defaults to the Task's registered project root; must resolve within the target orchestrator's base dir.
+- `orchestratorId`: Target host; omit for capacity-based placement among eligible hosts.
+- `spawnRequestId`: Idempotency key, same contract as relay_spawn_agent: a retried dispatch with the SAME spawnRequestId returns the existing spawn instead of double-spawning. Omitted → a fresh unique id is generated and a retried dispatch may spawn again, so pass an explicit id when you need retry-safe dispatch.
+- `waitForRegistrationMs`: How long to wait for the spawned agent to register before returning (default 0 = fire-and-forget; status stays `pending` and agentId null).
+- `verbose`: Include the redacted spawn-command summary (`command`) in the result.
+- `workflow`: A Task of a type that lands code (build, ui, refactor, debug, mechanical) starts the project's build-review workflow instead (#3091), exactly as relay_spawn_agent does: its run spawns the builder with your pin, orchestratorId and profile on the build step; the receipt carries `workflowRun`. Pass false to dispatch by hand.
+
+## relay_task_get
+
+Fetch a lean deliverable Task hydration: identity, status/stage, owner, linked issues, gate counts, short intent, and humanized times. Pass verbose:true for the complete legacy detail.
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+- `verbose`: Return the complete legacy Task detail, including full intent/body, gate rows, and dispatch projections.
+
+## relay_task_history
+
+List a Task's append-only event timeline (status, stage, gate, dependency, ref, attribution events).
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+
+## relay_task_list
+
+List Task awareness rows, optionally filtered by execution status, deliverable stage, team, project, or repo. `brief` is id/label/status only; the default lean rows omit paragraph titles and raw timestamps; `full`/verbose:true preserve the complete legacy summary shape. Defaults to your own Tasks (created by you, assigned to you, or owned by a coordinator role you hold); pass `mine:false` for every Task. `inFlight:true` drops done/canceled rows. Lean/brief rows page within the list budget, blocked/validating Tasks first.
+
+- `mine`: Default true: only the caller's own Tasks. false lists every Task.
+- `inFlight`: Exclude done/canceled Tasks.
+- `staleOwnerGone`: Only in_progress or blocked Tasks inactive for 7 days whose owner is gone.
+- `mode`: `brief`: id/label/status only. `lean` (default): concise execution rows with humanized updatedAt. `full`: complete legacy summary rows.
+- `verbose`: Back-compat alias for mode:"full".
+
+## relay_task_memory_append_decision
+
+Append a decision to a bound or coordinated Task's decision log. Append-only: use this for durable choices a retry agent must inherit.
+
+- `taskId`: Task id. Optional when the caller is bound to exactly one Task. TNNNN accepted.
+
+## relay_task_memory_append_ruled_out
+
+Append dead ends to a bound or coordinated Task's ruled-out ledger. Append-only: existing entries cannot be edited through this tool.
+
+- `taskId`: Task id. Optional when the caller is bound to exactly one Task. TNNNN accepted.
+
+## relay_task_memory_read
+
+Read the task-bound continuation envelope for a durable Task. If taskId is omitted, resolves the caller's bound Task; if provided, the Task must still be bound to the caller unless the caller has an admin scope.
+
+- `taskId`: Task id. Optional when the caller is bound to exactly one Task. TNNNN accepted.
+
+## relay_task_memory_replace_working_state
+
+Replace a bound or coordinated Task's current working-state memory. This is replaceable; later writes overwrite it.
+
+- `taskId`: Task id. Optional when the caller is bound to exactly one Task. TNNNN accepted.
+
+## relay_task_needs_validation
+
+List my shipped Tasks awaiting validation, including their validation items. Follows the current team coordinator after handover.
+
+## relay_task_record_gate
+
+Record a quality-gate run (typecheck, test, file-size, api-spec, smoke, …) in the append-only ledger. Idempotent by runId; latest run per gate wins.
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+
+## relay_task_remove_dependency
+
+Remove a task→task dependency edge.
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+- `dependsOnTaskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+
+## relay_task_remove_ref
+
+Remove a ref from a Task: an issue link (by issueRefId), the branch, and/or a commit (by sha).
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+
+## relay_task_set_review_hold
+
+Coordinator-only review-hold control (#2518). held:true parks a Task so a `complete` delivery is accepted and gate-validated but does NOT auto-land (no ingress; the branch is parked for review). held:false CLEARS the hold and immediately arms the exact reviewed delivery — pass expectedHeadSha matching relay_task_get's pendingReviewDelivery.sourceHeadSha (a mismatching HEAD returns 409 and leaves the hold unchanged). Authorized only for the Task's creator/resolved coordinator or an admin; the branch owner is rejected.
+
+- `taskId`: Task id (TNNNN accepted).
+- `held`: true = set the hold (require review before land); false = clear/approve & arm.
+- `expectedHeadSha`: Clear only: the reviewed HEAD to approve (CAS). Required when a held delivery is pending.
+- `reason`: Optional audit reason.
+
+## relay_task_set_stage
+
+Set the deliverable-position stage (none→uncommitted→committed-on-branch→landed-on-main→deploying→deployed). Normally driven by the land/deploy pipeline; exposed for manual/test use.
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+
+## relay_task_set_status
+
+Transition execution status (open|claimed|in_progress|validating|blocked|done|failed|canceled). validating means shipped with proof outstanding. done rejects open/failed validation unless an authorized coordinator passes force:true to override-close. blockedBy is required when status is 'blocked'. Appends to the audit ledger; never touches the claim lease. Returns {ok, id, status} by default; pass verbose:true for the full Task.
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+- `force`: Coordinator-only override-close despite open/failed validation. Only valid with done; carry-pending obligations remain enforced.
+- `verbose`: Return the full Task instead of the lean {ok, id, status} receipt.
+
+## relay_task_set_validation
+
+Coordinator-only: add/update a Task validation item by stable id. open waits for proof; met satisfies it; failed reopens work and wakes the coordinator. The last met item closes a shipped Task. Omit criterion when updating an existing item.
+
+## relay_task_update
+
+Update a deliverable Task's editable fields (title/label, intent, complexity, context, latest steer, doneWhen, dispatch, team, project/repo).
+
+- `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
+- `terminalStage`: null clears the override and restores the repo default.
+
+## relay_task_withdraw_land
+
+Coordinator-only withdraw of a workspace's standing land authorization (#2312/#2609). Revokes a `complete`-armed land a post-delivery review rejects: the workspace drops out of auto-land candidacy regardless of head position, even when the arming worker is dead. A true mid-flight revoke: an admitted kernel landing run and/or a dispatched merge command is CANCELED as part of the withdraw (fail-closed — only ever removes landability; a SHA already merged to main cannot be un-landed and refuses with 409). A later `complete` on the fixed SHA re-arms normally. Authorized only for a bound Task's creator/resolved coordinator, a fleet operator, or an admin; the branch owner is rejected.
+
+- `workspaceId`: Isolated workspace whose standing land authorization to withdraw.
+- `reason`: Optional audit reason (e.g. the P0 the review found).

package/docs/guides/workflows.md

@@ -0,0 +1,324 @@
+---
+title: Workflows and project roles
+summary: Let Humwick build and review a Task, customize the steps for your project, and resume or cancel a run.
+tags: [workflows, roles, tasks, build, review]
+---
+
+# Workflows and project roles
+
+Humwick helps agents work together on a project. A **Task** records a piece of work:
+what to do, how to know it is done, and which repository it belongs to. A
+**coordinator** is the agent directing that work. A **workflow** runs a sequence of
+steps for a Task so the coordinator does not have to launch each agent and pass
+results between them. A **role** gives a step's agent its instructions and working
+settings, such as which base agent profile to use.
+
+Use the bundled `build-review` workflow when a Task needs code built and reviewed.
+You can use it in your own repository without adding any workflow or role files.
+
+## Start your first build and review
+
+1. Create a Task with `relay_task_create`. Include the intended change, clear
+   acceptance criteria, the repository, and a work type such as `build`. Keep the
+   returned Task id.
+2. Call `relay_workflow_start` with the Task id:
+
+   ```json
+   {"workflow":"build-review","taskId":123}
+   ```
+
+3. Keep the returned run id. Humwick launches a builder. When it delivers, a fresh
+   reviewer checks the delivered commit. The builder's delivery waits for review;
+   it does not immediately merge. If review fails, findings go back to the builder
+   for a fix and another review. Repeated failures, blocked work or a failed step
+   return the run to the coordinator for a decision.
+4. Read progress with `relay_workflow_get`:
+
+   ```json
+   {"runId":"<returned-run-id>"}
+   ```
+
+   The response names the current step, agents, latest result and reason for a
+   stop. Add `"verbose":true` to read the full history and findings. Humwick sends
+   a result when the run finishes; you do not need a polling loop.
+5. After approval, Humwick lands the reviewed commit through your project's
+   configured checks. The bundled workflow also waits for CI on the landed commit
+   when your repository's CI is watched. Inspect the final result before reporting
+   success.
+
+For ordinary builder launches, this is also the default: a Task with a repository
+and type `build`, `ui`, `refactor`, `debug` or `mechanical` starts `build-review`
+when you use `relay_spawn_agent` or `relay_task_dispatch`. Review, research and
+operations Tasks, untyped Tasks and Tasks without a repository use direct launches.
+The launch response's `workflowRun` tells you when a workflow was started.
+
+If you intentionally need a direct launch, pass `"workflow":false` to the spawn
+or dispatch call. An already open run for that Task is returned rather than
+starting duplicate work. Do not bypass a running review by launching another
+builder for the same Task.
+
+## Choose the agents for a run
+
+Leave provider, model and host unset to let Humwick choose from eligible capacity.
+Use `pins` on `relay_workflow_start` when a particular step needs specific settings:
+
+```json
+{
+  "workflow":"build-review",
+  "taskId":123,
+  "pins":{"build":{"provider":"codex","effort":"high"}}
+}
+```
+
+Keys are step names, such as `build` and `review`. A pin can set `provider`, `model`,
+`effort`, `orchestratorId` (the host id), or `profile` (the role's base profile). A
+model pin needs a provider, either in the pin or the step definition. Pins override
+the workflow's step settings, which override role defaults and automatic selection.
+An explicit provider also overrides the workflow's preference for a reviewer from
+a different provider. The build profile must support editing and landing.
+
+On an ordinary spawn that starts a workflow, the spawn's provider, model, effort,
+host and profile become pins for its build step. Unsupported direct-spawn settings
+are rejected with guidance to use `workflow:false`; they are not silently dropped.
+
+## Customize the workflow in your project
+
+These paths are relative to **your repository**, not to a Humwick installation.
+Commit a file at `.agent-relay/workflows/<name>.yaml` to define a workflow. A file
+named `build-review.yaml` replaces the bundled workflow of that name. This minimal
+example builds, reviews, and lands after a passing review:
+
+```yaml
+description: Build and review a change in this project.
+steps:
+  build: { role: builder, task: input }
+  review: { role: reviewer, task: new, gate: review, crossProvider: build }
+routes:
+  build: { complete: review, failed: escalate, blocked: escalate }
+  review: { pass: land, fail: { to: build, max: 2, else: escalate }, failed: escalate, blocked: escalate }
+```
+
+`task: input` gives the builder your original Task. `task: new` gives the reviewer
+a separate review Task. `gate: review` tells Humwick which reported result is the
+review verdict. `crossProvider: build` prefers a reviewer from a different provider.
+Routes select the next step from the delivered outcome; the bounded failure route
+sends findings back to the builder and eventually asks the coordinator to decide.
+
+A role file at `.agent-relay/roles/<name>.md` supplies the instructions for that
+role. Override just `builder.md` to keep the bundled workflow while changing how
+your project's builder works:
+
+```markdown
+---
+description: Build changes using this project's conventions.
+extends: worker
+dispatch: { type: build }
+effort: high
+workspace: { mode: isolated }
+---
+
+Read the Task and the project's agent instructions. Implement the acceptance
+criteria, run this project's checks, commit and push the branch, then report with
+relay_task_deliver. Deliver complete for review and wait for the workflow result.
+```
+
+The YAML between `---` lines contains settings; the Markdown below it contains the
+agent's instructions (required, non-empty). Unknown fields are rejected. A project
+role wins over a bundled role of the same name, even when the workflow itself is
+bundled. To launch a role directly, pass `"role":"<name>"` instead of `profile` to the
+spawn or Task dispatch call.
+
+### Role file reference
+
+All fields are optional.
+
+| Field | Type / allowed values | Default | Meaning |
+| --- | --- | --- | --- |
+| `description` | non-empty string | none | One-line purpose of the role. |
+| `extends` | non-empty string | `worker` | Base agent profile name. |
+| `dispatch` | mapping of the four keys below | none | Work shape used to pick model and effort. |
+| `dispatch.type` | `build` `review` `research` `ops` `ui` `refactor` `debug` `mechanical` | none | Kind of work. |
+| `dispatch.complexity` | `trivial` `moderate` `complex` | none | Task size. |
+| `dispatch.contextFootprint` | `small` `medium` `large` | none | How much context the work needs. |
+| `dispatch.criticality` | `low` `normal` `high` | none | Cost of a mistake. |
+| `models` | mapping provider id to model name | none | Preferred model per provider. |
+| `effort` | `low` `medium` `high` `xhigh` `max` (checked at spawn) | profile default | Reasoning effort. |
+| `workspace` | mapping of the three keys below | none | Narrows workspace policy. |
+| `workspace.mode` | `isolated` `shared` `inherit` | profile default | Branch worktree or shared checkout. |
+| `workspace.landBlocked` | `true` only | off | Agent cannot land; a role can add a block, never lift one. |
+| `workspace.lifecycle` | `persistent` `transient` | profile default | Whether the agent ends after its step. |
+| `mcp` | list of server names | none | Servers selected from your committed `.mcp.json`. |
+| `skills` | list of project skill names | none | Required `.claude/skills/<name>/` skills at the run commit. Claude and Codex load native skills; other providers receive their full text in the first turn. Unknown names fail validation. |
+| `context` | list of repository-relative file paths | none | Full files at the run commit, included under Role context in the first turn. Missing paths fail validation. |
+| `contextTokenCap` | positive integer | `24000` | Combined estimated token budget for the selected context and skill files (characters / 4, rounded up per file). Role load and workflow start refuse over budget, listing every file and its token count. Increase the cap to allow larger roles. Already compiled launches retain full content and warn if over budget; nothing is truncated. |
+
+`models` and `mcp` examples:
+
+```yaml
+models: { claude: sonnet-5.5, codex: gpt-5.5 }
+mcp: [playtest]   # a key under mcpServers in .mcp.json at the same commit
+```
+
+A missing `.mcp.json` entry fails the launch. Do not list the built-in Humwick MCP server; it is always present.
+
+Selected servers still pass the base profile's project trust: the profile must
+enable and acknowledge project MCP. The default content review accepts a role's
+servers because they come from a landed commit. Commit review asks for an approval
+of each new role commit. A refused launch names the profile, the setting and the
+command that fixes it.
+
+Bundled roles, used when your repository has no role of that name:
+
+- `builder`: implement a Task and deliver it for review; fixes review findings.
+- `reviewer`: fresh read-only review of one delivered commit; returns the review verdict.
+- `verifier`: reproduce a Task's live check after deployment and return the evidence.
+- `slice-qa`: reproduce a committed slice proof independently.
+- `designer`: write a docs-only design for a Task and fix review findings.
+- `design-reviewer`: review one design head against its brief.
+- `plan-auditor`: audit a finished plan's acceptance on combined main and read back the recorded conformance.
+
+**Land customizations on your repository's default branch before using them.**
+Humwick fetches and reads workflow and role files at one default-branch commit.
+Uncommitted edits and changes on a feature branch do not change the workflow that
+reviews that branch. The run records the source and commit it used. A running run
+keeps its resolved definition; start a new run to pick up a later definition.
+
+## Resume work that needs a decision
+
+An `escalated` run is waiting for its coordinator to resolve the reported cause.
+Read it with `relay_workflow_get` and `verbose:true`, fix the cause, then call:
+
+```json
+{"runId":"<run-id>","note":"The dependency is ready. Continue the build."}
+```
+
+Use those arguments with `relay_workflow_resume`. It resumes the same run at the
+stopped step, keeps its history and gives it a fresh bounded attempt. You can name
+`step` to re-enter another step. A note reaches a retained builder as a message or
+a new agent as its instructions. `pins` replaces settings for the steps you name;
+an empty object for a step clears that step's pins.
+
+Choosing `"step":"land"` explicitly overrides the review verdict and arms landing
+of the last delivered commit. Use that only when your decision is to accept that
+commit. After landing, only the `ci-main` wait can be resumed.
+
+## Cancel a run
+
+Call `relay_workflow_cancel` with `runId` and a reason. It stops further steps and
+shuts down agents according to the workflow's cleanup settings; agents with
+unlanded work can be retained. Cancellation leaves the Task, its review hold and
+any already armed land unchanged. If you also intend to stop an armed land, use
+`relay_task_withdraw_land`; manage the Task separately. Canceling the Task itself
+also cancels its run. A completed run cannot be canceled.
+
+## Optional server capabilities
+
+The standard bundled build-review flow needs none of these switches. An operator
+can enable additional workflow features on the Humwick server; they default off:
+
+| Server variable | Set to | Enables |
+| --- | --- | --- |
+| `HUMWICK_WORKFLOW_COMPOSITION` | `1` | Child workflows and for-each workflow steps. |
+| `HUMWICK_WORKFLOW_SCRIPTS` | `1` | Script steps executed on a host. |
+| `HUMWICK_CHILD_WORKFLOWS` | `1` | Agents below a coordinator starting governed child workflow runs. |
+
+These are server settings, not variables to set in a builder's shell. If a run is
+rejected because a capability is unavailable, ask the server operator to enable
+it or choose a workflow that does not require it.
+
+## Read current help
+
+Call `relay_guide` with `{"action":"get","id":"workflows"}` whenever you need
+this guide. Use `{"action":"list"}` for the index or
+`{"action":"search","query":"review"}` to find guides. HTTP clients can use
+`GET /api/guides`, `GET /api/guides?q=review` and `GET /api/guides/workflows` with
+their usual authentication. Responses include the server version and source
+commit when known; each guide has a content revision. A later read returns the
+version served by the current server, even if your agent has been running since
+before an upgrade.
+
+### Ask the operator for a typed decision (v2)
+
+With `HUMWICK_WORKFLOW_DECISIONS=1` enabled on the hub, a `decision:` step
+files an ordinary operator decision owned by the run's coordinator seat. It appears
+in the decision list and chat with a link naming the run and step. Titles, context
+and choices can use the step's resolved `inputs`:
+
+```yaml
+triage:
+  inputs:
+    findings: ${{ steps.verify.outputs.findings }}
+    title: Approve verified Majors
+  decision:
+    title: ${{ inputs.title }}
+    context: Choose the findings to fix. Approving none is allowed.
+    multi-select: ${{ inputs.findings }}
+  output-schema:
+    type: object
+    additionalProperties: false
+    required: [approved, approvedIds, note]
+    properties:
+      approved: { type: array, items: { type: object, additionalProperties: true } }
+      approvedIds: { type: array, items: { type: string } }
+      note: { type: string }
+fixes:
+  for-each:
+    items: ${{ steps.triage.outputs.approved }}
+    concurrency: 2
+    do:
+      workflow: fix-finding
+      inputs: { finding: '${{ item }}' }
+```
+
+Each source object needs a unique nonempty string `id` and a nonempty `label`.
+`approved` contains the complete selected objects, including extra fields, in source
+order. `approvedIds` has those same IDs in source order; `note` is always a string.
+The operator submits IDs (`answers: {approved: [id, ...]}`), never replacement objects.
+An empty selection returns two empty arrays and starts zero for-each items.
+
+For a single choice, use `options: [{id: proceed, label: Proceed}, {id: stop, label: Stop}]`
+(or a string array). Its outputs are `choice` (the option ID) and `note`; later
+`if` expressions can read `steps.<step>.outputs.choice`. Unknown IDs and duplicate
+selections are rejected. If an answer fails `output-schema`, the decision stays
+open for correction.
+
+A decision wait has no ordinary step timeout or overdue escalation. Optional
+`decision.deadline: 2d` escalates the run when reached and withdraws the card.
+The decision and wait survive a hub restart. Cancelling the run withdraws its open
+card; late answers cannot advance the cancelled run. Choices are frozen at filing
+and bounded to 1,000 items and the workflow's normal 64 KiB value limit.
+
+To ask the run's coordinator first, set `decision.answeredBy: coordinator`.
+Omitting it (or using `operator`) keeps the operator card behavior above. The
+question, options and full multi-select items go to the run's starter, otherwise
+the Task's durable owner, otherwise the run coordinator, just like escalations.
+The wait and its frozen choices survive a hub restart.
+
+The recipient answers with the existing tool and the `waitKey` from the question:
+
+```json
+{
+  "runId": "wf-...",
+  "decision": {
+    "action": "answer",
+    "waitKey": "...",
+    "answers": { "approved": ["finding-a", "finding-c"] }
+  },
+  "note": "These have verified reproductions"
+}
+```
+
+Call `relay_workflow_resume` with that object. Single-choice questions instead use
+`"answers": { "choice": "option-id" }`. Outputs are exactly the operator answer's
+`approved`, `approvedIds`, `note` or `choice`, `note`; downstream `if` and `for-each`
+need no special handling.
+
+When unsure, use `"decision": { "action": "escalate", "waitKey": "..." }` and
+put the uncertainty in `note`. This creates the usual operator decision card with
+the same frozen choices and the note in its context. Only the operator can then
+answer. Only the addressed coordinator seat or an admin can answer or escalate;
+other agents receive 403. Cancelling invalidates the coordinator question and
+withdraws any escalated operator card. An old wait key cannot answer a later step.
+
+Reproduce both paths on a temporary dev hub:
+`env -u HUMWICK_TOKEN bun scripts/proof-6853-coordinator-decisions.ts`.

package/docs/license-faq.md

@@ -0,0 +1,37 @@
+# License FAQ
+
+Humwick is source-available; free for personal and internal company use;
+competing offerings require separate permission. Future releases use
+[PolyForm Shield 1.0.0](../LICENSE), with Exelerus AB as licensor.
+
+The license text, not this FAQ, controls. These examples explain typical uses;
+they do not add permissions or restrictions. In particular, Shield's New Products
+and Discontinued Products clauses remain part of the grant. The license includes
+the line of business notice for provider-independent runtimes and coordination
+software for teams of AI agents. Competition can exist even for a free offering
+or one using a different interface or platform.
+
+| Use | Typical result under Shield |
+| --- | --- |
+| Internal employee agents | An organization can run agents for its own work, including commercial internal operations, when it is not providing a competing product or service. |
+| Consultant installing for a customer | Installing and configuring the software for a customer's internal use is generally permitted when the offering does not compete. The customer must receive the license and required notices; a competing managed service needs separate permission. |
+| Noncompeting SaaS embedding | Permitted when the product does not compete with the software or a product Exelerus AB or its affiliates provides using it. Shield does not prohibit all SaaS use. |
+| Hosted agent-team service | A hosted substitute for the runtime or its coordination functionality generally competes and requires separate permission, subject to the license's express exceptions. |
+| Sold fork | Selling a fork that competes generally requires separate permission. Charging money alone is not the test: noncompeting distributions may be permitted, and free substitutes can compete. Preserve the license and required notices when distributing. |
+
+Request separate permission from Exelerus AB through the repository's maintainer
+contact. See [CONTRIBUTING.md](../CONTRIBUTING.md) and the
+[Contributor Agreement](../CLA.md) before contributing.
+
+## Earlier releases and dependencies
+
+Previously distributed MIT or AGPL versions retain their original grants. This
+change applies to future releases and does not retroactively revoke those rights.
+Third-party components keep their own licenses; see the
+[third-party notices](../THIRD_PARTY_NOTICES.md).
+
+The client and the private voice connector depend on the SDK version built from
+this repository. SDK tarballs published before this change keep their original
+AGPL grant; editing this repository cannot relicense them. Package metadata
+describes each package's own code, not a replacement license for its
+dependencies.