@kontourai/flow-agents 3.2.0 → 3.4.0

package/kits/builder/kit.json

@@ -27,6 +27,126 @@
       "reason": "learning-review invokes knowledge-capture (kits/knowledge/skills/knowledge-capture/SKILL.md) for durable knowledge storage"
     }
   ],
+  "first_party": true,
+  "workflow_triggers": [
+    {
+      "id": "builder-build-work",
+      "when": "implementation-work-detected",
+      "target_flow_id": "builder.build",
+      "default_skill": "deliver",
+      "conditional_skills": [
+        {
+          "when": "user-requested-tdd",
+          "skill": "tdd-workflow"
+        }
+      ],
+      "required_sequence": ["plan-work", "execute-plan", "review-work", "verify-work"],
+      "post_verify_targets": ["release-readiness", "learning-review"]
+    }
+  ],
+  "flow_step_actions": [
+    {
+      "flow_id": "builder.build",
+      "step_id": "pull-work",
+      "skills": ["pull-work"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "design-probe",
+      "skills": ["pickup-probe"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "plan",
+      "skills": ["plan-work"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "execute",
+      "skills": ["execute-plan"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "verify",
+      "skills": ["review-work", "verify-work"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "merge-ready",
+      "skills": ["evidence-gate"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "pr-open",
+      "skills": [],
+      "operations": ["publish-change"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "merge-ready-ci",
+      "skills": ["release-readiness"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "learn",
+      "skills": ["learning-review"]
+    },
+    {
+      "flow_id": "builder.build",
+      "step_id": "done",
+      "skills": []
+    }
+  ],
+  "hook_influence_expectations": [
+    {
+      "id": "dev-builder-build-requires-pickup-probe-before-plan",
+      "description": "missing pickup Probe before plan",
+      "tier": "design-target",
+      "must_include_guidance": [
+        "design-probe",
+        "accepted gaps",
+        "provider_state",
+        "conflict_risks"
+      ],
+      "must_include_actions": [
+        "route decision_gap back to design-probe/pickup Probe"
+      ]
+    },
+    {
+      "id": "dev-builder-review-before-verify-after-execute",
+      "description": "review-before-verify after execute",
+      "tier": "adapter",
+      "event": "PostToolUse",
+      "must_include_guidance": [
+        "Next: review",
+        "then verify",
+        "report only"
+      ],
+      "must_include_actions": [
+        "review-work for report-only critique before verify-work",
+        "not count critique.json as verification evidence"
+      ]
+    },
+    {
+      "id": "dev-builder-route-fresh-coding-prompt",
+      "description": "fresh coding prompt routes into Builder workflow",
+      "tier": "adapter",
+      "event": "UserPromptSubmit",
+      "must_include_guidance": [
+        "KIT WORKFLOW ROUTE",
+        "activate `deliver`",
+        "--flow-id builder.build",
+        "plan-work -> execute-plan -> review-work -> verify-work",
+        "release-readiness and learning-review"
+      ],
+      "must_include_actions": [
+        "use the `builder` kit's `builder.build` workflow before source edits",
+        "use deliver by default for coding/build work",
+        "do not bypass plan-work -> execute-plan -> review-work -> verify-work",
+        "publish, release readiness, and learning feedback"
+      ]
+    }
+  ],
   "skills": [
     {
       "id": "builder.builder-shape",

package/kits/builder/skills/continue-work/SKILL.md

@@ -49,6 +49,8 @@ Before doing anything else, restore the item's durable record into context throu
 
 If no durable record exists for the item, record that gap and rely on the issue body plus merged PRs/commits as the authoritative history.
 
+If the item was taken over from a stale incumbent (a `reclaimable` selection resumed via pull-work's **Takeover Protocol**, #294 / ADR 0021 §5), restoring the durable record IS the resumption: the deterministic slug points at the incumbent's existing `.kontourai/flow-agents/<slug>/`, and you continue the incumbent's branch (the `resume_branch` from `takeover-preflight`/the supersede output) — never a new branch, never a restarted plan. Takeover is resumption, not restart.
+
 ### 2. Determine the next undone slice
 
 From the issue body plus the merged PRs and commits referencing the issue, determine which slices have **landed** and which is the **next undone slice**.

package/kits/builder/skills/deliver/SKILL.md

@@ -247,6 +247,67 @@ After review, verification, evidence, and Goal Fit are clean for the same diff:
    npm run workflow:sidecar -- publish-delivery .kontourai/flow-agents/<slug>
    ```
 
+   **#356 — local reconcile-shape preflight.** `publish-delivery`/`record-release` now run a
+   local, pre-push **reconcile-shape preflight** on the session's `trust.bundle` before
+   copying anything into `delivery/`. It reuses the exact same claim-shape classification
+   `scripts/ci/trust-reconcile.js` enforces in CI (`scripts/lib/reconcile-shape.js`), so it
+   can never silently drift from what the required Trust Reconcile check actually does. If
+   the bundle is ADR-0020-invalid (e.g. a command-backed claim whose command isn't in the
+   reconcile manifest, an unwaived `assumed` claim, or an un-superseded disputed critique),
+   publish is **refused, fail-closed** — non-zero exit, a loud `REFUSING to publish` message
+   naming each invalid claim and its fix, and nothing is written to `delivery/`. This is
+   distinct from the existing fail-**soft** behavior when no `trust.bundle` exists yet at all
+   (still a silent no-op). When refused: fix the named claim (re-record evidence, add a
+   missing waiver, or supersede the disputed critique), then retry — do not attempt to push
+   past the refusal. You can also run the same check manually, any time before publish, to
+   catch a shape issue locally instead of discovering it minutes later in CI:
+
+   ```bash
+   npm run workflow:sidecar -- reconcile-preflight .kontourai/flow-agents/<slug>
+   ```
+
+   **#381 — manifest-lane constraint: which commands may be `kind:"command"` checks.** A check/claim
+   is only CI-reconcilable as `kind:"command"` (Surface's `test_output` evidence type) if its
+   command is a registered entry in the **trust-reconcile manifest** — the same
+   `{"id":..,"command":..,"lanes":[..]}` list `evals/ci/run-baseline.sh --manifest-json` emits
+   from its `CHECKS` array (source of truth: `evals/ci/run-baseline.sh` lines 12-67 for the
+   array, 166-182 for `emit_manifest_json`). `scripts/ci/trust-reconcile.js` resolves this same
+   manifest (`resolveManifest`/`manifestByCmd`, lines 292-370, 1101-1104) and reconciles a
+   `kind:"command"` claim's `execution.label` ONLY against it — a command not in the manifest
+   can never reconcile, and CI's reconciler names it exactly this way: `trust divergence: agent
+   claimed '<cmd>' passed; command is not in the reconcile manifest — a test_output claim must
+   name a manifest/required-lane command (CI cannot self-declare an arbitrary command)`. An
+   honest capture-backed check recorded against a real, passing, non-manifest command still
+   becomes this `not-run` divergence at CI reconcile time — it is not a shape bug to route
+   around, it is the manifest boundary working as designed. Anything that is not a registered
+   manifest command records as `kind:"external"` (a session-local attestation — e.g. a manual
+   code-review judgment) or `kind:"policy"` (a policy/compliance attestation — e.g. `promote`'s
+   claim, which carries no `command`/`execution.label` and therefore can never require a
+   manifest entry). This matters at every writer call that can produce a `kind:"command"`
+   check — `record-evidence`, `record-gate-claim --command`, and `record-check` — and again at
+   the `publish-delivery`/`reconcile-preflight` step above, which is where a non-manifest
+   command surfaces as a refusal before CI ever sees it. Gate claims recorded earlier in a
+   session are not special-cased here: the compose-safe writer path keeps every prior gate
+   claim's declared claim type intact across later `record-evidence`/`record-critique`/
+   `record-learning` calls, so a gate claim never needs to be the last write of a session to
+   survive.
+
+   - `kind:"command"` (manifest-backed) example — a real, currently-registered manifest entry
+     ("Source tree validation" → `npm run validate:source --`):
+
+     ```bash
+     npm run workflow:sidecar -- record-check .kontourai/flow-agents/<slug> -- npm run validate:source --
+     ```
+
+   - `kind:"external"` (non-manifest attestation) example — no `--command`, so nothing is
+     ever executed; the prose lives in `--summary`:
+
+     ```bash
+     npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+       --status pass \
+       --summary "Manual code review confirmed no regressions in the affected module."
+     ```
+
    **#379 — per-session delivery paths.** `publishDelivery()` writes to a PER-SESSION path
    `delivery/<slug>/trust.bundle` (+ `trust.checkpoint.json` companions), where `<slug>` is
    your session artifact dir's basename — NOT the old shared flat `delivery/trust.bundle`.
@@ -274,6 +335,60 @@ After review, verification, evidence, and Goal Fit are clean for the same diff:
    too — `git add -A delivery/` after the force-add. Do NOT hand-delete the flat
    `delivery/trust.bundle` in a delivery PR while other PRs may still seal to it.)
 
+   **#293 — verify-hold gate. HARD STOP.** Before committing/pushing/opening a PR/merging,
+   run the verify-hold check (it also runs automatically inside `publish-delivery` /
+   `record-release` / `advance-state --status delivered`, but run it explicitly here BEFORE
+   committing/pushing, since by the time `record-release` runs the branch may already be
+   pushed). **The command differs by this repo's configured assignment provider kind — a bare
+   `verify-hold <slug>` with no provider flag always defaults to `--assignment-provider
+   local-file` (`runVerifyHold`'s documented default), so on a `github`-provider repo it reads
+   no local claim record and silently resolves `free`/PASS regardless of the real GitHub hold
+   state. The local-file-only invocation below is NOT sufficient for a `github`-provider repo —
+   the github branch is MANDATORY for that provider kind:**
+
+   - **local-file provider** (this repo's configured assignment provider, from
+     `effective-assignment-provider-settings`, is `local-file`):
+
+     ```bash
+     npm run workflow:sidecar -- verify-hold .kontourai/flow-agents/<slug>
+     ```
+
+   - **github provider**: render-then-execute, mirroring `pull-work`'s SKILL.md claim-side
+     pattern for the same ADR 0021 §1 join — first read the effective state (no live `gh` call
+     happens inside `workflow-sidecar.ts`; the skill renders it here), then pass the rendered
+     `.effective` JSON into `verify-hold` via `--effective-state-json`:
+
+     ```bash
+     gh issue view <issue-number> --json assignees,labels,comments > /tmp/issue.json
+     npm run assignment-provider -- status \
+       --provider github \
+       --subject-id <slug> \
+       --issue-json /tmp/issue.json \
+       --liveness-stream <path-to-events.jsonl> \
+       --self-actor <actor> \
+       > /tmp/assignment-status.json
+     npm run workflow:sidecar -- verify-hold .kontourai/flow-agents/<slug> \
+       --assignment-provider github \
+       --effective-state-json /tmp/assignment-status.json
+     ```
+
+     (`/tmp/assignment-status.json`'s top-level shape is `{ role, provider, assignment,
+     effective }`; `verify-hold --effective-state-json` reads the `.effective` field, matching
+     `assignment-provider status`'s own output shape directly — no reshaping needed.)
+
+   This is the ONE point in the whole workflow that BLOCKS instead of warns (ADR 0021 §3). It
+   asks exactly one question: is this actor still the fresh, non-superseded holder of this
+   subject (or is the subject free/self-held)? **If the check reports not-fresh-holder (exit
+   non-zero, `ok:false` in the JSON result): DO NOT commit, push, open a PR, or merge.** This
+   is a different failure mode from the `publish-delivery`/reconcile-shape preflight paragraph
+   above — that one is about the trust *bundle's shape* being invalid; this one is about
+   *actor hold* — another actor holds a fresh claim on this subject, your own claim has gone
+   stale, or the subject is assigned to a human. Do not conflate the two "REFUSING to publish"
+   messages. When refused, follow the reconcile guidance (the CLI's own `guidance` field, or
+   verbatim): re-run `pull-work`/`pickup-probe` to discover the current holder and hand off
+   cleanly (`learning-review`/handoff), or, if a human confirms this session should resume
+   ownership, run `ensure-session --supersede-stale` before retrying.
+
 3. Commit the verified diff, including the force-added `delivery/<slug>/` trust artifacts.
 4. Push the branch.
 

package/kits/builder/skills/evidence-gate/SKILL.md

@@ -208,4 +208,16 @@ explicitly accepts them as unrelated residual risk.
 
 Evidence passes only when acceptance criteria, scope integrity, CI/runtime evidence, and residual risk are sufficient for the risk class.
 
+For an active Builder Flow run, record merge readiness only after this skill reaches `PASS`:
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+  --expectation merge-readiness \
+  --status pass \
+  --summary "Evidence gate passed: verified scope, acceptance evidence, review findings, and unresolved risks support provider review." \
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/evidence.json","summary":"Structured evidence verdict and acceptance coverage."}'
+```
+
+Record `fail` or `not_verified` when the verdict is not `PASS`. The resulting trust bundle is evaluated by Flow and may route back to verification, execution, planning, or Probe according to the canonical definition.
+
 After `PASS`, hand off to `publish-change` when the work is still local, or to `release-readiness` when the verified commit, pushed branch, provider change record or no-provider-change reason, provider checks, closing refs, structured evidence refs, and `Acceptance Evidence` table are available. After `FAIL` or `NOT_VERIFIED`, stop and name the missing work or evidence.

package/kits/builder/skills/execute-plan/SKILL.md

@@ -79,6 +79,15 @@ This skill owns orchestration between waves. The contracts own artifact continui
    - **Checkpoint**: update session file with completed tasks and next wave
    - Record worker progress with `npm run workflow:sidecar -- record-agent-event --artifact-dir <artifact-dir> --agent-id <worker-id> --kind evidence --status active|done --summary ...`
 9. After all waves: set session file `status: executed` and update `state.json` / `handoff.json` with `advance-state`
+10. For an active Builder Flow run, record the `implementation-scope` gate claim only after the changed-file scope and acceptance mapping are complete:
+    ```bash
+    npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+      --expectation implementation-scope \
+      --status pass \
+      --summary "Implementation completed within the planned scope; changed files and supported acceptance criteria are recorded." \
+      --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--execute-plan.md","summary":"Execution record with changed files, acceptance mapping, and worker evidence."}'
+    ```
+    Use `fail` or `not_verified` when scope integrity is unresolved. The sidecar writer synchronizes Flow; it does not declare the execute gate passed itself.
 
 The orchestrator is responsible for keeping root `state.json` current, and performs that update **exclusively** through `npm run workflow:sidecar -- advance-state` — never through a direct Write/Edit tool call against the sidecar path. `config-protection.js` blocks direct tool-mediated writes to `state.json` by design; that block is expected and correct, not a bug to route around. Workers should receive the workflow artifact root explicitly and append agent events under that root instead of inferring the slug or rewriting shared sidecars.
 

package/kits/builder/skills/learning-review/SKILL.md

@@ -20,6 +20,8 @@ Turn delivery outcomes into durable learning and follow-up work.
 ## Inputs
 
 - Release-readiness artifact, evidence-gate artifact, PR/issue links, deploy notes, incidents, telemetry, user feedback, and reviewer/verifier notes.
+- **Delegation routing telemetry** — the per-run economics records (`.kontourai/telemetry/economics.jsonl`) carry `delegations[]` with each sub-agent's `(role, resolved_model, outcome)`. Feed them to the routing-efficiency review (step 2a) to judge whether the model each role routes to is actually efficient.
+- **Kit/gate economics proposal ledger** — the same economics records, turned into a durable, idempotent per-kit/per-gate proposal ledger (`.kontourai/telemetry/learning-review-proposals.jsonl`) by `scripts/telemetry/learning-review-proposals.sh`. Feed it to the kit/gate economics review (step 2b).
 
 ## Artifact Contract
 
@@ -89,6 +91,55 @@ Before identifying durable learnings, write down the intended behavior, observed
 
 Classify learnings as product, technical, operational, workflow, test, documentation, eval, or agent-behavior learning.
 
+### 2a. Review Delegation Routing Efficiency
+
+Run the routing-efficiency analyzer over the run's economics records and review its proposals — the
+internal mirror of the #409 small-model value proof, applied to our own agent fan-out:
+
+```bash
+bash scripts/telemetry/routing-efficiency.sh .kontourai/telemetry/economics.jsonl
+```
+
+It emits ADVISORY per-`(role, model)` proposals (`escalate-minimum-tier`, `keep-tier`, `monitor`,
+`insufficient-signal`) with rationales, computed only from **measurable** outcomes — `unavailable`
+outcomes are excluded (a missing verdict is neither success nor failure; see
+`docs/specs/harness-capability-matrix.md`). Fold any actionable proposal into `learning.json`:
+
+- an `escalate-minimum-tier` / demote proposal → a `routing` entry (`target: "rule"`, naming the
+  `.datum/config.json` role→model change to consider) or `correction` with `type: "agent"`.
+- **These are proposals, never auto-applied.** A human ratifies the `.datum/config.json` change, which
+  then travels the normal deliver loop (ADR 0003 call 5). `insufficient-signal` proposals are recorded
+  as coverage notes, not routing changes.
+
+### 2b. Review Kit/Gate Economics Proposals
+
+Run the kit/gate economics analyzer over a window of economics records whenever enough new
+records have piled up since the last ledger entry — cadenced during a learning-review pass, not
+on a scheduler (see `--help` for the full flag set):
+
+```bash
+bash scripts/telemetry/learning-review-proposals.sh --since <last-run-until> --until <now>
+```
+
+It emits ADVISORY per-kit (`kit-review-cost-inflation`) and per-gate (`gate-false-block-review`,
+`gate-well-calibrated`) proposals, each citing paired `evidence.cost` + `evidence.defect` — never
+cost alone. `insufficient-data` is a valid, reportable outcome, not a bar to lower; never propose
+from noise. Surface every new (non-`already_proposed`) proposal to the human with its evidence,
+then record the ratify/reject/defer decision BEFORE any follow-on work exists:
+
+```bash
+bash scripts/telemetry/learning-review-decide.sh <ledger> <proposal-id> \
+  --ratify|--reject|--defer --decided-by <name> --rationale "<why>"
+```
+
+- **These are proposals, never auto-applied.** Nothing here writes to `kits/**`,
+  `.datum/config.json`, or any gate/flow config file.
+- Only on `--ratify`, create the ordinary follow-on backlog item and record it back onto the
+  proposal with `--follow-on-ref <ref>` — a follow-on may never cite an unratified proposal. A
+  later pass's effect-fill shows whether the ratified change actually moved the numbers.
+
+See `docs/specs/learning-review-proposals-contract.md` for the full contract.
+
 ### 3. Route Follow-Up
 
 Route raw ideas or ambiguous improvements to `idea-to-backlog`. Create GitHub issues only for executable follow-up. Use `evidence-gate` again when unresolved trust questions remain.

package/kits/builder/skills/plan-work/SKILL.md

@@ -137,8 +137,17 @@ The `tool-planner` prompt context must include the latest-base confirmation and
 4. Read the plan artifact
 5. Update session file: paste plan summary into `## Plan`, set `status: planned`
 6. Update `state.json` (`status: planned`, phase `planning`, next action) via `npm run workflow:sidecar -- advance-state` — never through a direct Write/Edit tool call (`config-protection.js` blocks that by design)
-7. Present the plan to the user
-8. If the user wants changes, re-delegate to tool-planner with feedback
+7. For an active Builder Flow run, record the `implementation-plan` gate claim after the plan and structured sidecars are complete:
+   ```bash
+   npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+     --expectation implementation-plan \
+     --status pass \
+     --summary "Implementation plan records files, sequencing, acceptance criteria, and required evidence." \
+     --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<session-basename>-plan.md","summary":"Structured implementation plan with acceptance and evidence traceability."}'
+   ```
+   Use `fail` or `not_verified` instead of `pass` when the plan contract is not satisfied. The sidecar writer synchronizes Flow; Flow, not this skill, decides whether execution is now active.
+8. Present the plan to the user
+9. If the user wants changes, re-delegate to tool-planner with feedback
 
 Never rely on conversational memory for the slug. Resolve the active artifact with `npm run workflow:sidecar -- current --format path` and pass that path to delegated agents.
 
@@ -198,22 +207,10 @@ Copied from the plan artifact. This is the stop condition for delivery.
 
 {context?}
 
-## Ad-hoc Direct Entry (Planning-Only or Non-`pull-work` Sessions)
-
-`ensure-session --flow-id <id>` without `--step-id` defaults `active_step_id` to the
-flow's FIRST step (`pull-work` for `builder.build`). For a session that legitimately
-enters mid-flow — e.g. planning directly from a portfolio work item without a
-`pull-work`/pickup artifact — pass the sanctioned override:
-
-```
-npm run workflow:sidecar -- ensure-session \
-  --flow-id builder.build --task-slug <slug> --step-id plan \
-  [--ad-hoc-reason "planning a directly-issued work item; no pull-work artifact"]
-```
+## Workflow Entry
 
-When `--step-id` names a step other than the flow's first step, `ensure-session` records
-`ad_hoc_entry: true` + `ad_hoc_reason` in `current.json`. This is the sanctioned way to
-enter a flow mid-stream: the explicit marker lets `stop-goal-fit` / `gate-review`
-distinguish an intentional direct entry from a stale or mis-stamped `active_step_id`,
-instead of silently defaulting to the first step and looking like a normal `pull-work`
-start.
+Do not create or restamp a `builder.build` run from this planning primitive. A Builder
+run enters through `pull-work`, then `design-probe`; Flow advances it to `plan` only after
+the declared upstream gates pass. When `plan-work` is invoked directly outside that
+product workflow, run it as a standalone primitive without `--flow-id builder.build` and
+do not report the omitted Builder prefix as complete.

package/kits/builder/skills/pull-work/SKILL.md

@@ -96,6 +96,8 @@ Use `github-cli` / `gh` when available to inspect issues, labels, milestones, pr
 
 Treat GitHub Issues as a `WorkItemProvider` and GitHub Projects as a `BoardProvider`, mapped through `context/contracts/work-item-contract.md`. Preserve provider-specific values in the artifact when useful, but use the contract's neutral fields for selection, grouping, and handoff.
 
+When a `BoardProvider` is configured, read the board Ready queue as the primary cross-repo selection input, ordered by configured priority and board position. Per-repo `WorkItemProvider` issue listing is the intake-gap detector: use it to surface open issues missing from the board, not as a silent fallback when the board has no ready items. If the configured board returns zero ready items, record and surface that warning as a dead readiness source before selecting or asking for alignment.
+
 Classify issues:
 
 - ready
@@ -115,6 +117,15 @@ npm run pull-work-provider -- \
 
 The helper preserves provider refs, project fields, blockers, PR links, and source artifact refs, then emits the work item contract fields plus readiness evidence. Use live provider state for final decisions; fixture output is only test evidence.
 
+When board state is available, read the Ready queue and intake gaps through the same helper:
+
+```bash
+npm run pull-work-provider -- \
+  --settings-json context/settings/backlog-provider-settings.json
+```
+
+For fixture-backed evaluation or cached provider JSON, pass `--items-json /path/to/project-items-and-open-issues.json`. The board output includes `ready_queue`, `intake_gaps`, and `warnings`; select from `ready_queue` first when it is populated.
+
 Before classifying provider-backed work as ready for pickup, fetch the latest target ref when network access and provider credentials are available, then compare the current target SHA to the work item's `planned_base_sha`. Record the current target ref/SHA, planned base ref/SHA, `commits-since`, planned age, changed files since the planned base, and changed-file intersections with `planning_scope_refs` in the pull-work artifact or helper output.
 
 Classify revision freshness as:
@@ -167,14 +178,24 @@ Read the returned `.effective.effective_state` and `.effective.reason` and class
 
 1. `effective_state: "held"` with `reason: "self_is_holder"` ⇒ `mine`: hand to `### 2. Enforce WIP And Shepherding`'s existing personal-WIP logic; do not re-offer as new, do not exclude as held-by-other.
 2. else `effective_state: "held"` (`reason: "fresh_liveness_heartbeat"` or `"liveness_claim_present_assignment_lagging"`) ⇒ excluded from the ready set by default.
-3. else `effective_state: "reclaimable"` ⇒ offered, flagged, with a warning; selecting it requires an explicit recorded opt-in (record in `reclaimable_override`, and/or `alignment_questions`), never a silent normal pick. This issue does not implement takeover — offering a `reclaimable` candidate, never auto-reclaiming it, is the correct scope boundary (Design Decision 2; full takeover protocol is ADR 0021 §5 / #294).
+3. else `effective_state: "reclaimable"` ⇒ offered, flagged, with a warning; selecting it requires an explicit recorded opt-in (record in `reclaimable_override`, and/or `alignment_questions`), never a silent normal pick. On selecting a `reclaimable` candidate, run the **Takeover Protocol** (#294, ADR 0021 §5) below — takeover is resumption, not restart: grace-beat, supersede, then continue the incumbent's branch. Never auto-reclaim without the recorded opt-in.
 4. else `effective_state: "human-held"` ⇒ surfaced, never auto-reclaimed (Design Decision 3 / ADR 0021 §6): record the assignee identity and idle duration (`effective.holder.assignee`, `effective.holder.idle_days`) in `alignment_questions` with a recommended answer (e.g. "assigned to `<assignee>`, idle `<idle_days>` days — reclaim?" recommending confirmation before proceeding), and select only on the user's explicit confirmation.
-5. else `effective_state: "free"` ⇒ offered normally — except a `superseded` liveness row (no active assignment, no fresh liveness) is surfaced but never auto-selected (full takeover semantics are #294; this is an accepted gap, not silently ignored), exactly as before this join upgrade.
+5. else `effective_state: "free"` ⇒ offered normally — including a `superseded` liveness row (no active assignment, no fresh liveness): now select-able via the **Takeover Protocol** below once the reclaimable/opt-in gate is satisfied (#294 implements the takeover semantics previously deferred here).
 
 An explicit user instruction to proceed despite a `held` or `reclaimable` classification (`--force`, "take it anyway", equivalent) overrides the exclusion/opt-in requirement; the override and its stated reason must be recorded in the artifact (`liveness_preflight`, `reclaimable_override`, and/or `priority_rationale`). A `human-held` classification is never overridden by `--force` alone — only the user's explicit answer to the recorded `alignment_questions` entry authorizes selecting it.
 
 This preflight now computes the **full** ADR 0021 §1 `assignment ⋈ liveness` join (previously liveness-only, pending #290): the assignment dimension is `#290`'s `AssignmentProvider` `status()` (`context/contracts/assignment-provider-contract.md`), joined against the same liveness stream this preflight already reads.
 
+#### Takeover Protocol (#294, ADR 0021 §5) — resumption, not restart
+
+When a `reclaimable` (or `superseded`-liveness) candidate is selected WITH the recorded opt-in, take it over by resuming the incumbent's work — never by starting a parallel branch or replanning. This is render-don't-execute: the CLI computes the decision and emits the exact steps; you run them.
+
+1. **Preflight:** `npm run workflow:sidecar -- takeover-preflight .kontourai/flow-agents/<slug>`. It returns `{action, effective_state, holder, resume_branch, grace_seconds, next_steps}`. Only `action: "grace-then-supersede"` proceeds; `back-off` (incumbent live/revived) ⇒ STOP and reselect; `ask-first` (human-held) ⇒ do not proceed without the user's explicit answer.
+2. **Grace beat:** wait `grace_seconds` (one heartbeat interval), then **re-run `takeover-preflight`**. If it now returns `back-off`, the incumbent revived — concede and reselect (this is the AC2 race guard). Proceed only if it is still `grace-then-supersede`.
+3. **Supersede:** `npm run workflow:sidecar -- ensure-session … --supersede-stale`. It re-checks the state and REFUSES if the incumbent revived in the meantime (a live `held` is never superseded), records the audit trail ("superseded actor X, last seen T, resuming from trust bundle"), and prints `resumed_branch`.
+4. **Resume the incumbent's branch — never a new one:** `git fetch origin <resume_branch> && git checkout <resume_branch>` (the `resume_branch` from step 1/3). Re-enter the existing artifact dir (the deterministic slug points at the same `.kontourai/flow-agents/<slug>/`); restore the durable record via the resume surface (#153) and continue from `handoff.json`/plan — do NOT re-plan or restart.
+5. **Record** the takeover (superseded actor, `resume_branch`, grace outcome) in `reclaimable_override`. If the superseded incumbent later wakes, it is blocked at publish by the verify-hold gate (#293) — the takeover is authoritative.
+
 `liveness claim`/`status`/`whoami` read/write the local runtime liveness stream, never GitHub issue/label/assignee state — this is not a provider mutation, and the two-provider-writes-only invariant in `## Contract` is unchanged by this slice. `#290` adds the one narrow, audited durable assignment claim that pairs with this liveness emit — see "Assignment Claim On Selection" below.
 
 ### 2. Enforce WIP And Shepherding
@@ -448,6 +469,14 @@ After a merge, automatic continuation may inspect the queue and write a new pull
 
 When the Pickup Gate passes and work is selected (not just a shepherding scan or WIP-only audit), record the gate claim for the Builder Kit `pull-work` step before handing off to `design-probe` or `plan-work`. This satisfies the `builder.pull-work.selected` gate expectation.
 
+Start the canonical Flow run before recording the first gate claim. This is idempotent for an existing run and projects Flow's current step and gate requirements into the sidecar:
+
+```bash
+flow-agents builder-run start --session-dir .kontourai/flow-agents/<slug>
+```
+
+Do not start at a later step. Flow owns advancement from `pull-work` after it evaluates the recorded evidence.
+
 Use the `selected_item_ids` as the evidence artifact ref and confirm that scope and acceptance criteria are present in the pull-work artifact:
 
 ```bash
@@ -458,6 +487,8 @@ npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact with selected_item_ids, scope, and acceptance criteria."}'
 ```
 
+The sidecar writer synchronizes an existing canonical Flow run after writing the trust bundle. If synchronization was interrupted, recover with the exact `next_action.command` from `state.json`; do not edit Flow state or restamp the active step.
+
 Use `--status fail` when the gate fails (blocker recorded but no selection made). Use `--status not_verified` only when the session has no active flow step (non-Builder-Kit usage).
 
 Record `--status fail` with a summary naming the blocker when stopping before selection. Do not record `pass` until `selected_item_ids` are confirmed and the pickup gate criteria above are met.

package/kits/builder/skills/release-readiness/SKILL.md

@@ -58,6 +58,18 @@ Use additional `--gate-json` and `--post-deploy-json` values for release, deploy
 
 After writing `release.json`, run artifact validation when available. If `record-release` is unavailable or blocked, keep the release decision as `HOLD` in the Markdown artifact and record the sidecar-write or validation blocker as a `NOT_VERIFIED` evidence gap until the structured release record can be written or the gap is explicitly accepted.
 
+For an active Builder Flow run, record the CI merge-readiness claim only for a `MERGE`, `RELEASE`, or `DEPLOY` decision backed by current provider checks:
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+  --expectation ci-merge-readiness \
+  --status pass \
+  --summary "Provider checks are current and passing; release-readiness decision and residual risks are recorded." \
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/release.json","summary":"Release-readiness decision with provider checks, rollback, and observability evidence."}'
+```
+
+Use `fail` or `not_verified` for `HOLD` and unresolved provider evidence. Flow owns the transition to learning after it verifies this claim.
+
 ## Workflow
 
 ### 1. Confirm Evidence

package/kits/knowledge/kit.json

@@ -4,6 +4,7 @@
   "name": "Knowledge Kit",
   "product_name": "Knowledge Kit",
   "description": "A Flow Kit for durable, gated knowledge storage. Provides a store contract with defined record types, mutation operations, and provenance rules — plus a default adapter backed by markdown files, YAML frontmatter, wikilinks, and a graph index.",
+  "first_party": true,
   "flows": [
     {
       "id": "knowledge.store-contract",
@@ -66,6 +67,14 @@
       "description": "Knowledge promote sub-flow (issue #313, the codebase-facing 'flow within a flow'): ingest a delivered session's artifacts -> distill schema-valid DRAFT decision/vocabulary/learning deltas per the decision-registry contract -> link provenance (PR, merge SHA, session archive, touched topics) -> health-check the registry for contradictions (overlapping subject nouns + divergent content) and propose merge-repair. Invokable standalone AND composable from the Builder promote step via uses_flow. PROPOSALS-ONLY: outputs land under <session>/proposals/ for the promote step to apply; the sub-flow never writes docs directly. Executable logic: promote/index.js."
     }
   ],
+  "workflow_triggers": [
+    {
+      "id": "knowledge-capture-work",
+      "when": "knowledge-capture-detected",
+      "target_flow_id": "knowledge.ingest",
+      "default_skill": "knowledge.knowledge-capture"
+    }
+  ],
   "docs": [
     {
       "id": "knowledge.readme",