@kontourai/flow-agents 3.5.0 → 3.7.0

package/docs/skills-map.md

@@ -8,13 +8,39 @@ This map groups the current skills by the user journey they support. The Builder
 
 For practical operator instructions and copy/paste prompts, see https://github.com/kontourai/flow-agents/blob/main/docs/workflow-usage-guide.md. For the shared cross-distribution contracts behind the workflow artifacts and gates, see https://github.com/kontourai/flow-agents/blob/main/docs/workflow-shared-contracts.md.
 
+## Builder Skill Roles
+
+`kits/builder/kit.json` is the machine-readable source for skill activation.
+Flow Definitions own step order, gates, route-backs, and trust expectations;
+the role matrix only maps each skill to that Flow-owned behavior.
+
+| Role | Skills | Activation |
+| --- | --- | --- |
+| Entrypoint | `builder-shape`, `deliver` | User selects the Builder product workflow; the skill coordinates but owns no step evidence. |
+| Profile | `fix-bug`, `tdd-workflow` | Explicit workflow variant; never selected as an automatic step action. |
+| Step producer | `idea-to-backlog`, `pull-work`, `pickup-probe`, `plan-work`, `execute-plan`, `review-work`, `verify-work`, `evidence-gate`, `release-readiness`, `learning-review` | Activated only for its declared Flow step; publishes only its declared expectations. |
+| Shared primitive | `design-probe` | Reused interview behavior with no Builder expectation ownership. |
+| Extension | `continue-work`, `gate-review` | Explicit continuation or retrospective operation outside automatic step actions. |
+
+Within the active `verify` step, `review-work` owns `clean-critique`: it records
+a report-only critique slice in `trust.bundle`. `verify-work` owns
+`acceptance-criteria`, `tests-evidence`, and applicable `policy-compliance`
+through command-backed behavior evidence. Use the public `flow-agents workflow`
+CLI for run status, evidence, and critique; skills must not call the
+package-internal writer directly.
+
+`builder.build` accepts exactly two public Work Item reference forms:
+`provider:id` and `owner/repo#numeric-id`. The latter is the GitHub-compatible
+adapter form; GitHub remains an optional adapter example. Do not invent
+arbitrary reference formats.
+
 - `builder-shape`: product-level Builder Kit shape invocation that guides `idea-to-backlog` without requiring the user to name the primitive, links `kits/builder/flows/shape.flow.json`, and stops at the backlog gate unless issue sync is explicit.
-- `idea-to-backlog`: discovery, idea separation, thinnest meaningful slice, shaping, prioritization, and executable GitHub issue creation.
+- `idea-to-backlog`: discovery, idea separation, thinnest meaningful slice, shaping, prioritization, and executable provider-backed work items; GitHub is an optional adapter.
 - `pull-work`: dynamic backlog selection, grouping/dependency checks, WIP awareness, worktree decision, and execution handoff; in Builder Kit build, every selected item or justified group needs fresh pickup Probe evidence before planning.
 - `design-probe`: generic one-question-at-a-time probing interview; Builder Kit uses this step before planning when the build flow needs shared understanding or a pickup decision.
 - `pickup-probe`: Builder Kit specialization of `design-probe` for selected work items; records scope, provider state, WIP/conflict scans, risks, decisions, unresolved questions, accepted gaps, and planning readiness.
 - `plan-work` / `execute-plan` / `deliver`: Definition Of Done, execution orchestration, and local delivery closure.
-- `continue-work`: advance a multi-slice work item to its next increment via a fresh-context handoff; restores the durable record (resume surface), derives the next undone slice from the issue plus merged PRs, and routes that slice **through** `pull-work` + `pickup-probe` (never around the gate) before handing off fresh per ADR 0013.
+- `continue-work`: advance a multi-slice work item to its next increment via an ephemeral fresh-context handoff; derives the next undone slice from the Work Item plus completed changes, then routes it **through** `pull-work` + `pickup-probe` before handing off fresh per ADR 0013.
 - `review-work`: report-only critique for quality, security triggers, architecture fit, and standards findings.
 - `verify-work`: behavior evidence mapped to acceptance criteria and Goal Fit.
 - `evidence-gate`: trust assessment for completed work: acceptance evidence, integrity checks, CI confidence, and next step.
@@ -35,7 +61,7 @@ flowchart LR
   Publish[publish-change<br/>commit / push / PR / CI]
   Release[release-readiness<br/>merge / release / deploy / docs decision]
   Learn[learning-review<br/>route follow-ups]
-  Backlog[(GitHub issues)]
+  Backlog[(Provider-backed work items)]
 
   Idea --> Shape --> Backlog --> Pickup --> Probe --> Build --> Review --> Verify --> GoalFit --> Trust --> Publish --> Release --> Learn
   Probe -->|not needed| Build
@@ -58,8 +84,8 @@ The operating model now has first-class coverage from idea intake through truste
 - Design probing is a generic skill named `design-probe`; in the Builder Kit build flow the step is still named `design-probe`, and the `pickup-probe` specialization records selected-work readiness before planning. `decision_gap` route-backs return there for missing pickup/planning decisions.
 - Product-level Builder Kit build may guide `pull-work -> design-probe / pickup-probe -> plan-work`; direct primitives still stop at their own gates and report the expected next step.
 - Broad continuation language does not carry across newly selected work after merge. Queue inspection is allowed, but planning the next item requires a fresh pickup Probe record.
-- Critique is owned by `review-work` and persisted in `critique.json`.
-- Verification is owned by `verify-work` and persisted in `evidence.json`.
+- Critique is owned by `review-work` as `clean-critique`, recorded directly by a delegated reviewer whose runtime identity differs from the active implementation actor, and stored through public `workflow critique` in its `trust.bundle` slice before verification.
+- Verification is owned by `verify-work` as `acceptance-criteria`, `tests-evidence`, and applicable `policy-compliance`, recorded as command-backed `trust.bundle` evidence with one criterion JSON record for every accepted criterion.
 - Trust evidence is assessed by `evidence-gate`; it decides whether completed work has enough proof and integrity to publish or continue fixing.
 - Publishing verified changes is the bridge between evidence and release readiness: commit the verified diff, push the branch, open or update the PR, and collect PR/CI evidence.
 - Merge/release/deploy decisioning is owned by `release-readiness` after the publish-change gate.
@@ -80,18 +106,18 @@ This view shows how each phase is composed. The left rail is the durable phase s
     <div class="phase-step"><span>01</span><strong>Discovery & shaping</strong></div>
     <div class="phase-lanes">
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>builder-shape</code> <code>idea-to-backlog</code></p></section>
-      <section class="phase-lane"><h3>Support</h3><p><code>search-first</code> <code>explore</code> <code>frontend-design</code> <code>github-cli</code> <code>knowledge-capture</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p><code>search-first</code> <code>explore</code> <code>frontend-design</code> optional <code>github-cli</code> adapter <code>knowledge-capture</code></p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, <code>shape-work</code>, prioritize work, sync executable backlog</p></section>
-      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Idea, slice, shape, and backlog gates. Writes shaped briefs and GitHub issue links in <code>.kontourai/flow-agents/&lt;slug&gt;/</code>.</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Idea, slice, shape, and backlog gates. Writes shaped briefs and provider work-item refs in <code>.kontourai/flow-agents/&lt;slug&gt;/</code>.</p></section>
     </div>
   </article>
   <article class="phase-row">
     <div class="phase-step"><span>02</span><strong>Backlog pickup</strong></div>
     <div class="phase-lanes">
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>pull-work</code></p></section>
-      <section class="phase-lane"><h3>Support</h3><p><code>github-cli</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p>optional <code>github-cli</code> adapter</p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>board snapshot, WIP check, grouping/dependency check, pickup Probe decision, worktree decision, <code>plan-work</code> handoff</p></section>
-      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Pickup gate and pickup Probe handoff. Writes selected issues, blockers, bundle justification, provider state, accepted gaps, worktree policy, expected modified files, conflict risks, and handoff notes.</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Pickup gate and pickup Probe handoff. Writes selected work items, blockers, bundle justification, provider state, accepted gaps, worktree policy, expected modified files, conflict risks, and handoff notes.</p></section>
     </div>
   </article>
   <article class="phase-row">
@@ -107,9 +133,9 @@ This view shows how each phase is composed. The left rail is the durable phase s
     <div class="phase-step"><span>04</span><strong>Evidence & release</strong></div>
     <div class="phase-lanes">
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>evidence-gate</code> <code>release-readiness</code></p></section>
-      <section class="phase-lane"><h3>Support</h3><p><code>github-cli</code> <code>eval-rebuild</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p>optional <code>github-cli</code> adapter <code>eval-rebuild</code></p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>criteria-to-evidence map, CI confidence, <code>scope-and-integrity-check</code>, publish-change, rollback review, observability review, post-deploy plan, final acceptance docs, remediate-ci</p></section>
-      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Evidence, publish-change, release, and docs gates. Writes confidence, integrity, commit/branch/PR/CI links, release scope, risk, rollback, deploy-readiness decisions, and durable documentation links.</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Evidence, publish-change, release, and docs gates. Writes confidence, integrity, commit/branch/provider-change/CI links, release scope, risk, rollback, deploy-readiness decisions, and durable documentation links.</p></section>
     </div>
   </article>
   <article class="phase-row">
@@ -125,10 +151,10 @@ This view shows how each phase is composed. The left rail is the durable phase s
 
 | Phase | Primary workflow skill | Supporting skills | Nested sections / future primitive candidates |
 | --- | --- | --- | --- |
-| Idea discovery and shaping | `builder-shape`, `idea-to-backlog` | `search-first`, `explore`, `frontend-design`, `github-cli`, `knowledge-capture` | intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, shape work, prioritize work, sync executable backlog |
-| Backlog pickup | `pull-work` | `github-cli` | board snapshot, WIP check, grouping/dependency check, Probe decision, worktree decision, handoff |
+| Idea discovery and shaping | `builder-shape`, `idea-to-backlog` | `search-first`, `explore`, `frontend-design`, optional `github-cli` adapter, `knowledge-capture` | intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, shape work, prioritize work, sync executable backlog |
+| Backlog pickup | `pull-work` | optional `github-cli` adapter | board snapshot, WIP check, grouping/dependency check, Probe decision, worktree decision, handoff |
 | Execution planning and build | `design-probe`, `pickup-probe`, `plan-work`, `execute-plan`, `review-work`, `verify-work` | `feedback-loop`, `browser-test`, `deliver`, `fix-bug`, `tdd-workflow` | Probe notes, Builder Kit Probe record, Definition Of Done, execution plan, parallel waves, implementation session state, critique report, verification report, Goal Fit Gate |
-| Evidence and release confidence | `evidence-gate`, `release-readiness` | `github-cli`, `eval-rebuild` | criteria-to-evidence map, CI confidence, scope/integrity check, publish-change, rollback review, observability review, final acceptance docs, post-deploy plan |
+| Evidence and release confidence | `evidence-gate`, `release-readiness` | optional `github-cli` adapter, `eval-rebuild` | criteria-to-evidence map, CI confidence, scope/integrity check, publish-change, rollback review, observability review, final acceptance docs, post-deploy plan |
 | Learning and improvement | `learning-review` | `knowledge-capture`, `idea-to-backlog`, `eval-rebuild` | facts vs interpretation, docs promotion review, follow-up routing, knowledge updates, eval/skill/backlog improvements |
 
 The highest-leverage future extractions are likely `shape-work`, `test-map`, `scope-and-integrity-check`, and `remediate-ci`. They are still nested because their behavior is present, but not yet large enough to need separate activation contracts.
@@ -137,28 +163,26 @@ The highest-leverage future extractions are likely `shape-work`, `test-map`, `sc
 
 Each workflow phase ends with an explicit gate and durable artifact:
 
-- `builder-shape` invokes Builder Kit shape, delegates to `idea-to-backlog`, links `kits/builder/flows/shape.flow.json`, and writes the standard `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` artifact.
-- `idea-to-backlog` writes `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` and produces shaped briefs plus GitHub issue links.
-- `pull-work` writes `.kontourai/flow-agents/<slug>/<slug>--pull-work.md` with selected issues, WIP notes, blockers, pickup Probe decisions or accepted gaps, worktree decision, expected modified files, conflict risks, and a `plan-work` handoff.
-- `plan-work` and `deliver` write `.kontourai/flow-agents/<slug>/<slug>--*.md` artifacts with `Definition Of Done`, `Goal Fit Gate`, and `Final Acceptance` sections.
-- `review-work` writes reviewer artifacts when available and updates `critique.json` with quality, security, architecture, standards, and resolution state.
-- `verify-work` writes verification artifacts and updates `evidence.json` with behavior evidence mapped to acceptance criteria.
-- `evidence-gate` writes `.kontourai/flow-agents/<slug>/<slug>--evidence-gate.md` with acceptance evidence, CI summary, integrity report, verdict, and next step.
-- `release-readiness` writes `.kontourai/flow-agents/<slug>/<slug>--release-readiness.md` with release scope, evidence reference, risk review, operational plan, rollback plan, observability plan, post-deploy checks, and decision.
-- `learning-review` writes `.kontourai/flow-agents/<slug>/<slug>--learning-review.md` with outcomes, evidence, decisions, gaps, follow-ups, knowledge updates, and verdict.
+- `builder-shape` selects a safe-slugged public shape run and delegates to `idea-to-backlog`.
+- `idea-to-backlog` owns `<slug>--idea-to-backlog.md` and the `builder.shape` slices in `trust.bundle`.
+- `pull-work` and `pickup-probe` own the selected-work and Probe sections of `<slug>--pull-work.md` plus their `trust.bundle` slices.
+- `plan-work` owns `<slug>--plan-work.md`, `acceptance.json`, `handoff.json`, and its `trust.bundle` plan slice; `execute-plan` owns the session execution report, `state.json`, and its scope slice.
+- `review-work` records report-only critique through public `workflow critique` and owns `clean-critique`.
+- `verify-work` records command-backed `acceptance-criteria`, `tests-evidence`, and applicable `policy-compliance` evidence in `trust.bundle`.
+- `evidence-gate` owns `<slug>--evidence-gate.md`; `release-readiness` owns `release.json`; `learning-review` owns `learning.json`; each also records its declared `trust.bundle` slice.
 
 Core gates:
 
 - Idea Gate: raw input is deduped, classified, and routed.
 - Slice Gate: each candidate has one outcome, one thinnest meaningful slice, and explicit split/bundle/dependency reasoning.
 - Shape Gate: scope, non-goals, risk, rollout notes, and acceptance criteria are stable enough.
-- Backlog Gate: GitHub issues represent executable or near-executable work.
+- Backlog Gate: provider-backed work items represent executable or near-executable work; GitHub issues are an optional adapter example.
 - Pickup Gate: selected work is ready, WIP is acceptable, and worktree policy is recorded.
 - Review Gate: report-only reviewers have no open blocking findings, or findings are explicitly accepted/deferred/false positive.
 - Verification Gate: implementation evidence exists from local, automated, browser, or runtime checks.
 - Goal Fit Gate: the original user outcome is satisfied, gaps are explicit, and local/project/global scope is clear.
 - Evidence Gate: acceptance criteria are mapped to falsifiable evidence and scope integrity is checked.
-- Publish Change Gate: verified changes are committed, pushed, represented by a PR or explicit no-PR decision, and PR checks/CI are linked.
+- Publish Change Gate: verified changes are committed, pushed, represented by a provider change record or explicit no-provider-change decision, and available provider checks/CI are linked.
 - Release Gate: CI, docs, rollout, rollback, observability, and owner concerns are addressed for the risk class.
 - Docs Gate: accepted planning artifacts are archived and promoted into durable docs when useful.
 - Learning Gate: failures and recurring patterns are routed to tests, evals, skills, backlog, or knowledge capture.
@@ -169,7 +193,7 @@ Core gates:
 flowchart LR
   Idea[Idea / vague goal]
   BacklogSkill[idea-to-backlog]
-  Issue[Executable GitHub issue]
+  Issue[Executable provider-backed work item]
   Pull[pull-work]
   Probe[design-probe]
   Worktree[worktree decision]
@@ -203,7 +227,7 @@ Workflow evals are layered to match this map:
 
 - Static contract evals guard non-negotiable skill boundaries.
 - Behavioral activation evals check that agents choose the right workflow and stop at gates.
-- Artifact quality evals inspect durable session artifacts and GitHub issue drafts.
+- Artifact quality evals inspect durable session artifacts and provider work-item drafts; GitHub is an optional adapter example.
 - Adversarial evals exercise premature coding, vague issues, missing CI, weakened tests, and prototype promotion risks.
 - End-to-end evals cover `idea-to-backlog -> pull-work -> design-probe -> plan-work -> execute-plan -> review-work -> verify-work -> goal-fit -> evidence-gate` selectively.
 

package/docs/spec/builder-flow-runtime.md

@@ -28,26 +28,29 @@ expectations, and Builder Kit's structured action map.
 
 ## Entry And Synchronization
 
-A Builder session is created at the Flow Definition's entry step by the workflow
-sidecar. If automatic startup reports a failure, retry the canonical operation with:
+A Builder session is created at the Flow Definition's entry step by the public
+workflow command. Start the selected Work Item with its stable, human-readable
+provider reference:
 
 ```bash
-flow-agents builder-run start --session-dir .kontourai/flow-agents/<slug>
+flow-agents workflow start --flow builder.build --work-item <provider-ref> \
+  --assignment-provider <configured-kind> \
+  [--effective-state-json <provider-status.json>]
 ```
 
-`ensure-session --flow-id builder.build` starts or loads this canonical run before
-returning. When the local assignment provider durably assigns the exact Work Item
-to the resolved workflow actor, `ensure-session` rereads that record and produces
-the declared `builder.pull-work.selected` claim through the normal Surface trust
-bundle path. Flow evaluates that subject-bound evidence and advances to
-`design-probe`; Flow Agents does not write a transition or gate outcome directly.
-Skipped ownership, unresolved actors, precomputed state, and non-local providers do
-not produce selection evidence and remain at `pull-work`.
+The configured provider resolves and durably assigns the exact Work Item to the
+workflow actor. Non-local adapters pass their standard status result to start;
+Flow Agents retains it as provenance and creates a local runtime lease mirror.
+The start path then produces the declared
+`builder.pull-work.selected` claim through the normal Surface trust bundle path.
+Flow evaluates that subject-bound evidence and advances to `design-probe`; Flow
+Agents does not write a transition or gate outcome directly. Skipped ownership,
+unresolved actors, precomputed state, and unavailable provider resolution do not
+produce selection evidence and remain at `pull-work`.
 
-The command remains the explicit recovery path if Flow startup fails after sidecar
-creation; the failure is returned to the caller and no substitute run state is
-invented. Runtime hooks keep projected actions advisory while the agent performs
-their declared skills and operations.
+If start fails, the failure is returned to the caller and no substitute run state
+is invented. Runtime hooks keep projected actions advisory while the agent
+performs their declared skills and operations.
 
 Sidecars written by 3.4.2 may still contain `next_action.enforcement`. The 1.0
 schema accepts that deprecated field for artifact compatibility, but current
@@ -58,38 +61,36 @@ Item reference as the Flow run subject. It is idempotent for an existing canonic
 run. A direct primitive session without a Builder Flow stamp remains independent and
 does not create a Flow run.
 
-After a gate producer writes `trust.bundle`, the sidecar writer synchronizes an
-existing run automatically. Interrupted clients can replay the projected command:
+After a gate producer writes `trust.bundle`, the public evidence path
+synchronizes the existing run while holding the assignment subject lock.
+Synchronization is digest-idempotent: the same trust bundle is not attached
+twice.
+
+## Public Status And Recovery
+
+Inspect an interrupted canonical Builder session with:
 
 ```bash
-flow-agents builder-run sync --session-dir .kontourai/flow-agents/<slug>
+flow-agents workflow status --session-dir .kontourai/flow-agents/<slug> --json
 ```
 
-Synchronization is digest-idempotent. The same trust bundle is not attached twice.
-Inspection loads the run without evaluating it, so invalid evidence is rejected
-before Flow mutation.
-
-## Recovery
+`workflow status` is read-only. It loads the canonical run and reports its run
+identity, definition, status, current step, projected `next_action`, and bound
+session directory. Callers cannot select a different run or force a step.
 
-Recover an interrupted canonical Builder session with:
+For an active interrupted run, continue from the reported `next_action` and use
+its exact idempotent command to recheck the canonical state. The current step's
+producer records gate evidence through `flow-agents workflow evidence`; that
+public operation validates assignment and observations before attaching the new
+trust-bundle digest and evaluating the gate. For a paused run, the current
+assignment actor resumes it with an explicit reason:
 
 ```bash
-flow-agents builder-run recover --session-dir .kontourai/flow-agents/<slug>
+flow-agents workflow resume --session-dir .kontourai/flow-agents/<slug> --reason <text>
 ```
 
-`recover` derives the Flow run id from the session directory slug; callers cannot
-select a run id or step. It requires exactly one non-empty
-`state.work_item_refs` entry, loads the existing run through Flow's canonical load
-API, and verifies that the ref matches persisted `state.subject` and, when present,
-`state.params.subject`. A missing, foreign, or corrupt run fails closed and is not
-created or repaired.
-
-Recovery is load/validate/project only. It computes the complete projection before
-updating `state.json`, the matching global `current.json`, and matching per-actor
-current pointers. It does not inspect or attach `trust.bundle`, evaluate gates, or
-write any file in `.kontourai/flow/runs/<slug>/`; the complete Flow run tree remains
-byte-identical. Use `sync`, not `recover`, to attach recorded evidence and evaluate
-the current gate.
+Do not use a private synchronization or recovery command, manually project run
+state, or create a replacement run for a missing, foreign, or corrupt binding.
 
 ## Trust Binding
 
@@ -99,7 +100,7 @@ claims are ignored for that gate. A relevant claim with a missing or different
 subject reference is rejected; Flow is not mutated.
 
 A failed gate claim may include a Flow classifier through
-`record-gate-claim --status fail --route-reason <reason>`. Flow validates the reason
+`flow-agents workflow evidence --status fail --route-reason <reason>`. Flow validates the reason
 against the gate's `on_route_back` map and owns both the destination and attempt
 budget. Flow Agents only projects the resulting attempt and maximum into `state.json`.
 
@@ -112,9 +113,46 @@ While a run is active, `state.json` contains:
 - `next_action.skills`: ordered Builder skills for the current step.
 - `next_action.operations`: ordered non-skill product operations when present.
 - `next_action.summary`: required gate claims derived from the Flow Definition.
-- `next_action.command`: the exact idempotent synchronization command.
+- `next_action.command`: the exact idempotent public status command for reorientation.
 
 Workflow steering surfaces these fields on session start and prompt submission. The
 Stop hook treats an unfinished canonical Flow run as active even during pickup or
 planning, blocks a premature stop in block mode, and does not release its liveness
 claim. A run is complete only when Flow reaches its terminal step.
+# Builder Lifecycle Authority
+
+The canonical Flow run owns pause, resume, and cancellation. The current assignment actor may
+pause, resume, or release its own assignment with a reason. Cancellation and archival require
+an Ed25519-signed authorization record conforming to
+`schemas/builder-lifecycle-authorization.schema.json`. The record is operation-bound and binds
+the request to the run id, selected Work Item, current assignment actor, immutable external
+request reference, nonce, and expiry. Its signing key must be pinned in the durable
+`.flow-agents/lifecycle-authority-keys.json` registry. Runtime or harness adapters hold the
+private key and capture the signed record from a user/operator channel they trust; agent-authored
+prose or an unsigned model-written file is not cancellation authority.
+
+This is an audit and policy boundary, not authentication against a process with unrestricted
+access as the same operating-system user. The harness must keep its signing key outside the
+agent process and enforce its own filesystem or process isolation when the agent is adversarial.
+The repository hooks protect the pinned public-key registry from ordinary agent writes, but are
+explicitly not an operating-system security boundary.
+Adversarial-runtime authentication is tracked separately in Flow Agents issue #545. Flow's
+current lifecycle authority vocabulary also requires agent-owned pause/resume events to use the
+closest available `operator_request` shape; a distinct canonical runtime authority is tracked in
+Flow issue #118.
+
+```text
+flow-agents builder-run pause --session-dir <dir> --reason <text>
+flow-agents builder-run resume --session-dir <dir> --reason <text>
+flow-agents builder-run cancel --session-dir <dir> --authorization-file <record.json>
+flow-agents builder-run release-assignment --session-dir <dir> --reason <text>
+flow-agents builder-run archive --session-dir <dir> --authorization-file <record.json>
+```
+
+Pause and resume verify the live assignment actor under the assignment lock, and preserve the
+current Flow step and assignment. Assignment release does not
+change the Flow run. Cancellation changes Flow first and then idempotently releases the owning
+assignment while holding the same lock; a successfully consumed cancellation nonce cannot be
+replayed. Archive accepts only completed or canceled runs, moves the session under
+`.kontourai/flow-agents/archive/<slug>/`, and retains the canonical Flow run. None of these
+operations deletes a branch or worktree; cleanup requires a separate provider-aware action.