@kontourai/flow-agents 2.3.0 → 3.0.0

package/kits/builder/skills/design-probe/SKILL.md

@@ -107,21 +107,21 @@ This applies whether the probe is run directly (generic) or as part of a Builder
 **Claim 1 — Pickup readiness** (probe passed, goal fit and scope confirmed):
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --expectation pickup-probe-readiness \
   --status pass \
   --summary "Design probe passed: goal fit confirmed, scope aligned, planning readiness verified." \
-  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--<artifact>.md","summary":"Design-probe artifact with decisions, accepted gaps, and planning readiness."}'
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--<artifact>.md","summary":"Design-probe artifact with decisions, accepted gaps, and planning readiness."}'
 ```
 
 **Claim 2 — Probe decisions captured**:
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --expectation probe-decisions-or-accepted-gaps \
   --status pass \
   --summary "Probe decisions recorded: decisions made, unresolved questions explicit, planning readiness confirmed." \
-  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--<artifact>.md","summary":"Design-probe artifact with decisions and accepted gaps."}'
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--<artifact>.md","summary":"Design-probe artifact with decisions and accepted gaps."}'
 ```
 
 Record both claims when shared understanding exists and the next action is `plan-work` or equivalent. Use `--status fail` when stopping due to an unresolved blocker. Skip these claims entirely when `design-probe` is used outside a Builder Kit flow (no active `builder.build` flow step in `current.json`).

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

@@ -28,10 +28,13 @@ Evidence Gate is not Release Readiness. It asks whether completed work has enoug
 - Provider change / branch / check run links when available.
 - Changed-file summary.
 - Active TODOs, issue links, and release/rollback notes.
+- Cross-repo dependency/provider coverage matrix when work spans multiple
+  products, package-manager roots, generated artifact locations, install
+  scripts, CI, or shared workflow guidance.
 
 ## Artifact Contract
 
-Write or update `.flow-agents/<slug>/<slug>--evidence-gate.md` with:
+Write or update `.kontourai/flow-agents/<slug>/<slug>--evidence-gate.md` with:
 
 - `intent`: issue/brief, acceptance criteria, non-goals, risk class
 - `evidence_manifest`: command/check name, source, timestamp, result, link/output pointer
@@ -102,6 +105,13 @@ Check for process gaming or accidental drift:
 
 Sensitive areas include auth, security middleware, data migrations, CI config, deployment scripts, feature flags, test helpers, lint/type config, payment, crypto, and filesystem/network operations.
 
+For multi-repo or cross-product changes, require an explicit coverage matrix
+before a clean pass. The matrix must list every affected product/repo root and
+the status of build/test evidence, dependency/security review, provider/CI
+evidence, and any accepted gaps. A clean evidence verdict requires every
+applicable root to be covered or a human-accepted gap recorded with the reason.
+Do not infer cross-product coverage from a passing subset.
+
 ### 4. CI And Flake Assessment
 
 Use `github-cli` / `gh` when available.
@@ -179,6 +189,21 @@ Use `git` and the active `ChangeProvider` adapter when available to:
 
 If commit, push, provider change publication, or provider checks are blocked, keep the release path at `NOT_VERIFIED` or `HOLD` until the blocker is resolved or explicitly accepted by the user.
 
+### 8. Dependency And External-Audit Coverage
+
+When dependency review is in scope, evidence-gate must preserve both local
+inventory evidence and external advisory/audit evidence separately. External
+audit commands and registry/advisory lookups may disclose private dependency
+metadata; if the execution policy rejects the command or the user has not
+explicitly approved that disclosure, record the affected roots as
+`NOT_VERIFIED` for external audit and name the privacy/approval blocker.
+
+For cross-product work, a dependency/security lane can pass only when every
+applicable package-manager root has one of these recorded outcomes: `pass`,
+`fail`, `skip_no_manifest`, or an accepted `not_verified` gap. Existing
+vulnerabilities are still `FAIL` for the dependency lane unless the user
+explicitly accepts them as unrelated residual risk.
+
 ## Gate
 
 Evidence passes only when acceptance criteria, scope integrity, CI/runtime evidence, and residual risk are sufficient for the risk class.

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

@@ -29,7 +29,7 @@ This skill owns orchestration between waves. The contracts own artifact continui
 
 ## Input
 
-- **Plan artifact path**: path to the `-plan.md` file in `.flow-agents/<slug>/`
+- **Plan artifact path**: path to the `-plan.md` file in `.kontourai/flow-agents/<slug>/`
 - **Session file path**: the session file to update with progress
 
 ## Workflow
@@ -67,7 +67,7 @@ This skill owns orchestration between waves. The contracts own artifact continui
    - 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`
 
-The orchestrator owns root `state.json` updates. Workers should receive the workflow artifact root explicitly and append agent events under that root instead of inferring the slug or rewriting shared sidecars.
+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.
 
 ## Pre-Fan-Out Freshness Re-Check
 

package/kits/builder/skills/fix-bug/SKILL.md

@@ -70,6 +70,8 @@ Root cause from tool-planner.
 - iteration 2: pass — bug fixed, no regressions
 ```
 
+`<branch>` is the branch recorded in `state.json`'s `branch` field (`ensure-session` derives `agent/<actor>/<slug>`; an explicit `--branch` flag overrides on a new session). `ensure-session` only records the name — creating and checking out the actual git branch/worktree remains this skill's responsibility.
+
 ## Workflow
 
 ### 1. Create session file

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

@@ -12,7 +12,7 @@ Classify gate fires and suspected misses from the session's `trust.bundle` by ca
 - **Advisory-only**: proposes fixes, never applies them. No finding may instruct auto-application of any fix.
 - Never writes to `scripts/hooks/` or any flow file.
 - Reads the local `trust.bundle` file only. Does NOT fall back to `command-log.jsonl`, `.goal-fit-block-streak.json`, or `evidence.json` direct reads as primary inputs.
-- If no `trust.bundle` is present at `.flow-agents/<slug>/trust.bundle`, reports `NOT_VERIFIED` and stops. Does not silently degrade to bespoke sidecar reads.
+- If no `trust.bundle` is present at `.kontourai/flow-agents/<slug>/trust.bundle`, reports `NOT_VERIFIED` and stops. Does not silently degrade to bespoke sidecar reads.
 - Routes all telemetry, `learning.json` writes, and correction routing through `learning-review`. Gate-review never calls `record-learning` directly.
 - Reads `state.json` for lifecycle context only (phase, status). `state.json` is NOT a trust claim per ADR 0010.
 - Reads `context/gate-awareness.md` for vocabulary alignment when available.
@@ -23,7 +23,7 @@ Classify gate fires and suspected misses from the session's `trust.bundle` by ca
 
 ## Inputs
 
-- `trust.bundle` at `.flow-agents/<slug>/trust.bundle` (produced by ADR 0010 Phase 1 dual-write in `workflow-sidecar`).
+- `trust.bundle` at `.kontourai/flow-agents/<slug>/trust.bundle` (produced by ADR 0010 Phase 1 dual-write in `workflow-sidecar`).
 
   **Dependency**: this file is NOT present at `origin/main @ a9b8fd6`; it requires ADR 0010 Phase 1 to be built and merged (owned by `arch/goal-fit-gate-trust-bundle`). Do not begin execution until Phase 1 has landed or a fixture is agreed with that owner.
 
@@ -64,12 +64,12 @@ Classify gate fires and suspected misses from the session's `trust.bundle` by ca
   | `stale` | Claim data is outdated; gate had stale input. |
   | `unknown` | No event found; claim was never evaluated. |
 
-- `state.json` at `.flow-agents/<slug>/state.json` (lifecycle context; not a trust input).
+- `state.json` at `.kontourai/flow-agents/<slug>/state.json` (lifecycle context; not a trust input).
 - Optional: seeded fixture `trust.bundle` path for testing before Phase 1 produces real bundles.
 
 ## Artifact Contract
 
-Write the following artifacts under `.flow-agents/<slug>/`:
+Write the following artifacts under `.kontourai/flow-agents/<slug>/`:
 
 ### `<slug>--gate-review.md`
 
@@ -161,7 +161,7 @@ Cross-reference with `state.json` phase at the time of the block to confirm the
 
 ### Step 1 — Locate trust.bundle
 
-Resolve `.flow-agents/<slug>/trust.bundle`. The slug is the most recent active session (by `current.json` or `state.json` newest-mtime). If absent, surface the blocker:
+Resolve `.kontourai/flow-agents/<slug>/trust.bundle`. The slug is the most recent active session (by `current.json` or `state.json` newest-mtime). If absent, surface the blocker:
 
 ```
 [gate-review] trust.bundle absent — NOT_VERIFIED. Build ADR 0010 Phase 1 first.
@@ -209,7 +209,7 @@ Pass the `gate-review.inquiries.json` path as additional reviewer notes to `lear
 
 Example invocation note:
 ```
-gate-review InquiryRecords at .flow-agents/<slug>/gate-review.inquiries.json:
+gate-review InquiryRecords at .kontourai/flow-agents/<slug>/gate-review.inquiries.json:
 - <N> record(s): calibration counts
 - gate fired: <true/false>
 - calibration: correct=<n>, false_block=<n>, missed_block=<n>

package/kits/builder/skills/idea-to-backlog/SKILL.md

@@ -23,7 +23,7 @@ Convert raw ideas into shaped, prioritized, executable backlog without starting
 
 ## Artifact Contract
 
-Create or update `.flow-agents/<slug>/<slug>--idea-to-backlog.md` with:
+Create or update `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` with:
 
 - `source_ideas`: raw inputs and dedupe links
 - `idea_inventory`: one record per distinct idea, classification, outcome, and reason

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

@@ -14,7 +14,7 @@ Turn delivery outcomes into durable learning and follow-up work.
 - Capture facts, decisions, and follow-up issues separately.
 - Feed actionable changes back to `idea-to-backlog`, GitHub issues, tests, docs, or knowledge.
 - Use `knowledge-capture` or `observe` when the learning should persist beyond the repo.
-- Compare long-lived docs against the local `.flow-agents/<slug>/` plan and the final acceptance artifact so implementation intent is not lost after merge.
+- Compare long-lived docs against the local `.kontourai/flow-agents/<slug>/` plan and the final acceptance artifact so implementation intent is not lost after merge.
 - Treat `learning-review` as the terminal closeout decision point for correction telemetry. Compare intended behavior to observed behavior before writing `learning.json`, then record either `correction.needed: false` for a clean run or `correction.needed: true` for a mismatch.
 
 ## Inputs
@@ -23,7 +23,7 @@ Turn delivery outcomes into durable learning and follow-up work.
 
 ## Artifact Contract
 
-Create or update `.flow-agents/<slug>/<slug>--learning-review.md` with:
+Create or update `.kontourai/flow-agents/<slug>/<slug>--learning-review.md` with:
 
 - `scope`: delivered work, issue/PR/release links, dates
 - `outcomes`: expected vs observed behavior and signals
@@ -39,7 +39,7 @@ Create or update `.flow-agents/<slug>/<slug>--learning-review.md` with:
 When the repository provides `npm run workflow:sidecar --`, also write `learning.json` with:
 
 ```bash
-npm run workflow:sidecar -- record-learning .flow-agents/<slug> \
+npm run workflow:sidecar -- record-learning .kontourai/flow-agents/<slug> \
   --status learned \
   --record-json '{"id":"...","source_refs":["release.json"],"outcome":"success","facts":["..."],"interpretation":"...","routing":[{"target":"none","action":"No follow-up required after intended-vs-observed closeout.","status":"completed"}],"correction":{"needed":false,"evidence":"Acceptance, release, docs promotion, and learning closeout behaved as intended."}}' \
   --summary "..."
@@ -112,21 +112,21 @@ After `learning.json` is written and the learning verdict is `LEARNED` or `FOLLO
 **Claim 1 — Decision evidence** (durable decisions from the build are recorded):
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --expectation decision-evidence \
   --status pass \
   --summary "Build decisions recorded: <decision-count> decisions captured, correction.<needed> recorded." \
-  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/learning.json","summary":"learning.json with decisions and correction state."}'
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/learning.json","summary":"learning.json with decisions and correction state."}'
 ```
 
 **Claim 2 — Learning evidence** (learnings from delivery are recorded for future work):
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --expectation learning-evidence \
   --status pass \
   --summary "Learning evidence captured: <outcome> outcome, facts recorded, routing complete." \
-  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/learning.json","summary":"learning.json with outcomes, facts, and routing."}'
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/learning.json","summary":"learning.json with outcomes, facts, and routing."}'
 ```
 
 Record both claims immediately after `record-learning` succeeds and artifact validation passes. Use `--status fail` when `record-learning` fails or when learning cannot be captured (verdict `BLOCKED`). Use `--status not_verified` only when the session has no active Builder Kit flow step.

package/kits/builder/skills/pickup-probe/SKILL.md

@@ -49,6 +49,7 @@ Challenge the selected work against the repository before planning:
 - Challenge glossary conflicts immediately: if a user or issue uses a term differently than `CONTEXT.md`, ask which meaning is authoritative before planning.
 - Discuss concrete scenarios when boundaries are fuzzy, especially around ownership, provider state, workflow gates, and stop-short behavior.
 - Check whether the selected work is still ready after WIP, conflicts, blockers, dependency freshness, and expected modified files are considered.
+- If the pull-work artifact flags the selected item `reclaimable`, treat the recorded opt-in as a decision to re-confirm (not silently accept) when material drift or time has passed since pull-work's preflight ran.
 - Keep downstream issues and non-goals out of scope unless they are explicit contract consumers for the selected work.
 - Ask one question at a time when a decision is needed, include a recommended answer, and record the answer immediately.
 - Record unresolved questions as blockers unless the user or orchestrator explicitly accepts proceeding with the gap.
@@ -91,21 +92,21 @@ When the Planning Gate passes, record the two gate claims for the Builder Kit `d
 **Claim 1 — Pickup readiness** (probe passed, goal fit and scope confirmed):
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --expectation pickup-probe-readiness \
   --status pass \
   --summary "Pickup probe passed: goal fit confirmed, blockers checked, dependencies reviewed, acceptance criteria verified." \
-  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact recording probe status, scope, and planning readiness."}'
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact recording probe status, scope, and planning readiness."}'
 ```
 
 **Claim 2 — Probe decisions captured** (decisions, accepted gaps, and planning readiness are recorded):
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --expectation probe-decisions-or-accepted-gaps \
   --status pass \
   --summary "Probe decisions recorded: <decision-count> decisions, <gap-count> accepted gaps. Planning readiness: <ready|accepted_gap_ready>." \
-  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact with decisions, accepted gaps, and planning handoff."}'
+  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact with decisions, accepted gaps, and planning handoff."}'
 ```
 
 Record both claims together immediately when the gate passes. Use `--status fail` when the gate fails (unresolved blocker or decision gap). Use `--status not_verified` only when the session has no active flow step.

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

@@ -98,11 +98,11 @@ The `tool-planner` prompt context must include the latest-base confirmation and
 
 ## Workflow
 
-1. Create session file in `.flow-agents/<slug>/` if one wasn't provided:
+1. Create session file in `.kontourai/flow-agents/<slug>/` if one wasn't provided:
    - Filename: `<slug>--plan-work.md`
    - `status: planning`, `type: plan-work`
-   - Create or update `state.json` with phase `planning`
-   - use `npm run workflow:sidecar -- ensure-session --source-request ... --summary ... --criterion ...` when the repository provides it; this also writes `.flow-agents/current.json`
+   - Create or update `state.json` (phase `planning`) via `npm run workflow:sidecar -- init-plan`/`ensure-session` — never through a direct Write/Edit tool call (`config-protection.js` blocks that by design)
+   - use `npm run workflow:sidecar -- ensure-session --source-request ... --summary ... --criterion ...` when the repository provides it; this also writes `.kontourai/flow-agents/current.json`
    - **Builder Kit build flow**: add `--flow-id builder.build` to the `ensure-session` call when `plan-work` is invoked from `deliver`, from the Builder Kit `build` flow, or from a pick-up-and-build request after `pull-work`. This activates the FlowDefinition-driven path so producers fire and gates enforce on builder.* claims. Do NOT add `--flow-id` for direct/ad-hoc primitive `plan-work` invocations that are not part of a builder-flow.
 2. Delegate to `tool-planner`:
    ```
@@ -127,7 +127,7 @@ The `tool-planner` prompt context must include the latest-base confirmation and
    - if task-to-acceptance mapping is unclear, send the planner feedback before presenting the plan as ready
 4. Read the plan artifact
 5. Update session file: paste plan summary into `## Plan`, set `status: planned`
-6. Update `state.json` with `status: planned`, phase `planning`, and the next action
+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
 
@@ -177,12 +177,34 @@ Structured plan from tool-planner (pasted from artifact).
 Copied from the plan artifact. This is the stop condition for delivery.
 ```
 
+`<branch>` is the branch recorded in `state.json`'s `branch` field (`ensure-session` derives `agent/<actor>/<slug>`; an explicit `--branch` flag overrides on a new session). `ensure-session` only records the name — creating and checking out the actual git branch/worktree remains this skill's responsibility.
+
 ## Output
 
-- Session file in `.flow-agents/<slug>/` with status `planned`
+- Session file in `.kontourai/flow-agents/<slug>/` with status `planned`
 - Plan artifact: `<session-basename>-plan.md`
 - Structured sidecars: `state.json`, `acceptance.json`, and `handoff.json`
 - The plan artifact is the source of truth — tool-worker agents read it directly
 - Plan artifact follows `context/contracts/planning-contract.md`
 
 {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"]
+```
+
+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.

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

@@ -10,6 +10,8 @@ Select ready backlog work and prepare a bounded execution handoff without implem
 ## Contract
 
 - Use `context/contracts/work-item-contract.md` as the source vocabulary for provider-backed work item shape, provider roles, and capability flags.
+- Use `context/contracts/assignment-provider-contract.md` as the second source vocabulary for durable ownership: the `AssignmentProvider` operations (`claim`/`release`/`supersede`/`status`/`list`), the assignment ⋈ liveness join's effective-state enum (`held`/`reclaimable`/`human-held`/`free`), and the versioned claim-record format come from that contract, not from this skill.
+- `pull-work` may perform exactly two provider-adjacent writes at selection: the liveness claim (ADR 0012, ephemeral, local runtime presence stream — see "1a. Liveness Selection Preflight" / "Liveness Claim On Selection") and the durable assignment claim (`context/contracts/assignment-provider-contract.md`, GitHub assignee/label/comment or a local-file record — see "Assignment Claim On Selection"); no other provider mutation is added to this skill.
 - Read the configured backlog provider dynamically.
 - Select one issue or a coherent issue group.
 - Do not implement code.
@@ -29,14 +31,18 @@ Select ready backlog work and prepare a bounded execution handoff without implem
 - Repository or working directory.
 - Optional labels, milestone, project board, assignee, or priority filter.
 - Optional WIP limit or current in-progress context.
-- Existing `.flow-agents/<slug>/` artifacts, PRs, and CI/review queues.
+- Existing `.kontourai/flow-agents/<slug>/` artifacts, PRs, and CI/review queues.
 
 ## Artifact Contract
 
-Create or update `.flow-agents/<slug>/<slug>--pull-work.md` with:
+Create or update `.kontourai/flow-agents/<slug>/<slug>--pull-work.md` with:
 
 - `board_snapshot`: filters, issue list, labels, milestone/provider milestone state, project fields, state, blockers
 - `wip_assessment`: active work, reviews, verification, CI remediation, with personal WIP separated from global conflict context
+- `liveness_preflight`: per-candidate `{subjectId, state: held|reclaimable|human-held|free|mine, holder_actor?, status_raw, effective_reason?}` plus `self_actor`/`self_actor_source`, computed via `liveness status --json` + `liveness whoami --json` joined with `assignment-provider status`'s `effective_state`/`reason` (see "1a. Liveness Selection Preflight"); `self_actor` is captured exactly once per pull-work pass and pinned for reuse (see "1a. Liveness Selection Preflight" and "Liveness Claim On Selection" — never re-derived per claim call); this is now the **full** ADR 0021 §1 `assignment ⋈ liveness` join (previously liveness-only pending #290 — #290 has landed)
+- `reclaimable_override`: recorded only when a `reclaimable` (stale) candidate is selected, or when `--force`/an explicit user instruction overrides a `held` exclusion — the explicit opt-in decision and its stated reason (see "1a. Liveness Selection Preflight")
+- `liveness_claim`: per selected item, `{subjectId, actor, emitted_at, ttl_seconds}`; on any claim-emit failure, `{skipped: <stderr reason>}` instead — fail-open (never block selection on a liveness-emit failure) but never silent: the skip reason is also surfaced in pull-work's user-facing output, and an unresolved-actor failure additionally names the remediation (`--actor <id>` / `FLOW_AGENTS_ACTOR=<id>` / a supported runtime), matching ADR 0012; also carries an optional `post_claim_conflict: {other_actor, detected_at}` when the post-claim re-check (see "Post-Claim Conflict Re-check") detects a double-hold
+- `assignment_claim`: per selected item, `{provider: "github"|"local-file", subject_id, actor, command_evidence, confirmed_status}` — the durable-claim analog of `selected_item_ids`: provider kind, subject id, actor, the rendered/executed command evidence (`gh_commands`/`claim_comment_body` for `github`, the local-file `claim` invocation for `local-file`), and the confirmed `assignment-provider status` result for each selected item, recorded once the post-claim confirmation in "Assignment Claim On Selection" succeeds; see `context/contracts/assignment-provider-contract.md` for the underlying claim-record shape
 - `my_active_work`: local worktrees, dirty branches, open PRs by the current user, active sidecars, and in-flight review/verification/release work owned by the current user
 - `shepherding_candidates`: personal PRs, worktrees, or sidecars that should be reviewed, fixed, published, merged, abandoned, or cleaned before starting more work
 - `stale_worktrees`: worktrees with no open PR, no recent activity, merged/abandoned branches, or unclear ownership that need an explicit keep/remove decision
@@ -111,6 +117,56 @@ Missing `planned_base_sha` is not fresh. Record it as an explicit `NOT_VERIFIED`
 
 Return vague work to `idea-to-backlog` instead of inventing scope.
 
+### 1a. Liveness Selection Preflight
+
+Resolve the current actor once per `pull-work` pass and pin it for reuse:
+
+```bash
+npm run workflow:sidecar -- liveness whoami --json
+```
+
+Capture the returned `actor` value as `self_actor` (and its `source` as `self_actor_source`) exactly once per pass. Reuse this pinned `self_actor` value explicitly via `--actor <self_actor>` on every subsequent `liveness claim` call in the same pass (see "Liveness Claim On Selection" below) — never re-derive the actor mid-pass, since ancestry/session-based resolution could otherwise resolve to a different value across separate calls within the same pass and silently defeat the "who am I" pinning this preflight depends on.
+
+Read the full liveness stream once per pass (omit `--subject` to get every row):
+
+```bash
+npm run workflow:sidecar -- liveness status --json
+```
+
+For each ready candidate, derive `subjectId` via:
+
+```bash
+npm run workflow:sidecar -- resolve-slug <owner>/<repo>#<issue-number>
+```
+
+then group all rows for that `subjectId` by subject (classify per subject, not per row), reading each row's raw `status` field (never `label`). Detect the liveness-only double-hold case first, before computing the full assignment ⋈ liveness join below: when a `verified` row for an actor other than self and a `verified` row for the resolved self actor both exist on the same subject, that is a double-hold — surface it as `held` plus an explicit conflict warning (per ADR 0012 §4 detection: "a false-stale double-hold ... is detected ... not prevented"), never silently resolve it to `mine`.
+
+Otherwise, compute the full ADR 0021 §1 `assignment ⋈ liveness` join per candidate via `assignment-provider status` (using the effective provider kind, repo, artifact root, `label_name`, and `claim_comment_marker` from `effective-assignment-provider-settings` — see "Assignment Claim On Selection" below — joined against the same liveness stream already read above):
+
+```bash
+npm run assignment-provider -- status \
+  --provider <github|local-file> \
+  --subject-id <subjectId> \
+  --liveness-stream <path-to-events.jsonl> \
+  --self-actor <self_actor>
+  # github: --issue-json <path-to-gh-issue-view-json|-> --label-name <label> --claim-comment-marker <marker>
+  # local-file: --artifact-root <dir>
+```
+
+Read the returned `.effective.effective_state` and `.effective.reason` and classify in this precedence order:
+
+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).
+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.
+
+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.
+
+`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
 
 Before selecting new work, check whether review, verification, release, or CI remediation is congested. Separate the current user's active work from global conflict context.
@@ -119,7 +175,7 @@ Personal WIP scan:
 
 - Inspect local worktrees and branches for dirty state, unpublished commits, merged branches, abandoned branches, and unclear ownership.
 - Inspect open PRs authored by the current user and record review/check state, requested changes, mergeability, and whether the PR needs shepherding.
-- Inspect active `.flow-agents/<slug>/` sidecars owned by the current user or current session, especially `planning`, `planned`, `in_progress`, `verifying`, `needs_decision`, `not_verified`, `failed`, and `blocked`.
+- Inspect active `.kontourai/flow-agents/<slug>/` sidecars owned by the current user or current session, especially `planning`, `planned`, `in_progress`, `verifying`, `needs_decision`, `not_verified`, `failed`, and `blocked`.
 - Classify personal items into `my_active_work`, `shepherding_candidates`, `stale_worktrees`, and `open_prs_by_me`.
 
 Global conflict scan:
@@ -187,6 +243,93 @@ Use these compact examples as the expected artifact shape when selecting or reje
 - **dogfood-alpha implementation work**: `selected_scope`: single-item implementation slice in the dogfood-alpha milestone; `priority_rationale`: high delivery alignment and unlocks product dogfood evidence, but only selected if dependencies are closed or explicitly accepted; `dependencies`: list blocked-by issues, required artifacts, and pickup Probe freshness; `wip_conflict_notes`: require worktree isolation when implementation overlaps active files or release lanes; `grouping_check`: Work Item Group only when one item hard-blocks the implementation and the dependency sequence is part of the same acceptance signal; `alignment_questions`: ask the narrow scope question before `plan-work` if the issue could expand into provider adapters or runtime orchestration.
 - **blocked cross-product dependency**: `selected_scope`: no implementation selection; `priority_rationale`: defer because a higher-priority item in another product/repo is blocked by an unresolved dependency or missing provider state; `dependencies`: name the blocker, owner/repo when known, and freshness check; `wip_conflict_notes`: record any release-lane or provider-state conflict as the reason to stop; `grouping_check`: unsafe-group unless explicit dependency sequencing and shared acceptance justify a bundle; `alignment_questions`: ask whether to shepherd/unblock the dependency, return to shaping, or choose the next ready independent item.
 
+### Liveness Claim On Selection
+
+Once `selected_item_ids` is finalized at the end of `### 3. Select Work`, before handoff to `plan-work`, for each selected item run:
+
+```bash
+npm run workflow:sidecar -- liveness claim <subjectId> --actor <self_actor>
+```
+
+using the same `subjectId` computed via `resolve-slug` during the preflight, and the same pinned `self_actor` captured once from `liveness whoami --json` at the start of this pass (`### 1a. Liveness Selection Preflight`) — always pass `--actor <self_actor>` explicitly on every claim in this pass; never a fresh derivation per claim call.
+
+Record the result in `liveness_claim` as `{subjectId, actor, emitted_at, ttl_seconds}`. On any claim-emit failure (non-zero exit, unresolved actor, or liveness disabled/unavailable), record `{skipped: <stderr reason>}` in `liveness_claim` instead — fail-open, never block selection on a liveness-emit failure — and also surface that skip reason in pull-work's user-facing output; never silent. When the failure is specifically an unresolved-actor failure, additionally name the remediation (`--actor <id>` / `FLOW_AGENTS_ACTOR=<id>` / a supported runtime), matching `liveness claim`'s own error message.
+
+### Post-Claim Conflict Re-check
+
+After emitting claims for the selected item(s) above, re-read liveness status for those same subjects:
+
+```bash
+npm run workflow:sidecar -- liveness status --json --subject <subjectId>
+```
+
+If another actor's fresh (`verified`) claim now coexists with this session's own just-emitted claim on the same subject — a double-hold, per ADR 0012 §4 ("a false-stale double-hold (two fresh claims on one subject) is detected ... via Hachure `conflictRules`/`conflictedClaims`, not prevented") — surface the conflict prominently in the user-facing output and instruct the user to coordinate before proceeding; do not silently continue as if the selection were exclusive. Record the detected conflict in `liveness_claim`'s `post_claim_conflict` field.
+
+When a double-hold is detected, immediately run the deterministic tiebreaker using the same pinned `self_actor` and the same `subjectId` already in scope:
+
+```bash
+npm run workflow:sidecar -- liveness verdict <subjectId> --json
+```
+
+`liveness verdict` is a read-only, lock-free CLI action that computes `{subjectId, winner, losers, reason, holders}` as a pure function of the shared liveness stream: among the subject's currently-fresh claim holders, the one whose current `claim` event has the earliest `at` wins; an exact-timestamp tie breaks by ascending actor-id string comparison (`reason: "tie-actor-lexicographic"`) — the SAME verdict for the SAME stream state regardless of which actor invokes it.
+
+Branch on the returned `winner.actor`:
+
+- If `winner.actor !== self_actor`, this session is the loser: immediately run `npm run workflow:sidecar -- liveness release <subjectId> --actor <self_actor>`, extend `post_claim_conflict` with `{verdict_reason, winner_actor, conceded: true}`, and return to `### 3. Select Work` to reselect within the same `pull-work` pass — excluding the just-released subject — before any handoff to `plan-work`.
+- If `winner.actor === self_actor`, this session wins: record the verdict for transparency (`{verdict_reason, winner_actor: self_actor, conceded: false}`) in `post_claim_conflict` and proceed normally; do not release.
+
+Honesty note: this re-check narrows, but does not close, the read-then-write race between the preflight's read and the claim's write. The verdict-and-release loop above closes the "detected but advisory-only" gap ADR 0012 §4 names for THIS session's own double-hold — the loser deterministically concedes and re-selects within the same pass, a new convergence guarantee this slice adds — but it still does not provide true mutual exclusion across the read-then-write race window itself; that residual is unchanged from before. `#290`'s provider assignment lease closes this gap for the **local-file** provider only: `claim`/`release`/`supersede` there are wrapped in a per-subject `mkdir`-lock (atomic create, EEXIST-spin, staleness reclaim), so two concurrent local-file `claim` calls on the same subject genuinely cannot both win — true mutual exclusion, not just detection. The **GitHub** provider (assignee/label/claim-comment) remains advisory/last-writer: `render-claim`/`render-supersede` emit `gh` argv for the calling skill to run, and nothing about a GitHub issue's assignee/label/comment state gives atomic compare-and-swap across two concurrent skill invocations — the post-claim `status` re-check above still only *detects* a lost race after the fact, it does not *prevent* one. Do not read "provider assignment lease" as closing the GitHub race; only the `verify-hold` publish gate (#293), not yet implemented, would do that for GitHub.
+
+### Assignment Claim On Selection
+
+After the post-claim liveness conflict re-check above resolves (no double-hold detected, or this session won the deterministic tiebreaker and any loser has reselected) and `selected_item_ids` is otherwise ready to finalize, perform the durable assignment claim — the second and last provider-adjacent write this skill performs (see `## Contract`) — before recording `selected_item_ids` as final and before any handoff to `plan-work`.
+
+Resolve the effective assignment provider settings once per pass:
+
+```bash
+npm run effective-assignment-provider-settings -- --repo-path . --json
+```
+
+If the result is `status: ask_user`, ask the user which `AssignmentProvider` (`github` or `local-file`) to use before claiming; do not silently assume. If `status: configured`, use the returned `settings.provider.kind`, `settings.provider.repo`, `settings.policy.label_name`, and `settings.policy.claim_comment_marker` for every call below.
+
+For each selected item's `subjectId` (the same `subjectId` resolved via `resolve-slug` and used throughout this pass):
+
+- **`kind: "github"`**: build an `--input-json` payload with `repo` (`{owner, name}`), `issue_number`, `assignee_login` (the current actor's GitHub login when known), `existing_assignee_login` and `existing_comment_id` (only when superseding an already-recorded `reclaimable`/confirmed `human-held` candidate — otherwise omit), `label_name`, `claim_comment_marker`, `ttl_seconds`, `branch`, and `artifact_dir`, then render:
+
+  ```bash
+  npm run assignment-provider -- render-claim \
+    --provider github \
+    --subject-id <subjectId> \
+    --input-json <path> \
+    --actor-json <path>
+  ```
+
+  Execute every command in the returned `gh_commands` array **verbatim** via the Bash tool, in order — never freehand `gh` text. Each `gh_commands` entry is an **argv array** (one element per argument, e.g. `["gh", "issue", "comment", "9101", "--repo", "kontourai/flow-agents", "--body", "..."]`) and MUST be executed as argv — every element passed as its own separate Bash-tool argument — **never** concatenated into a single shell-command string, and **never** run via `bash -c "..."` or any other shell re-interpretation of the joined elements. `claim_comment_body` (and, when superseding, `previous_record`) can carry attacker-influenced text (see the GitHub claim-record sanitization note in `context/contracts/assignment-provider-contract.md`); concatenating argv elements into a shell string before execution would reintroduce a shell-injection surface this render/execute split is designed to avoid. Record the rendered `record`, `claim_comment_body`, and each executed `gh_commands` entry as evidence.
+
+- **`kind: "local-file"`**: call the local-file `claim` subcommand directly — no render step, since this is the one path that performs real I/O inside the CLI itself:
+
+  ```bash
+  npm run assignment-provider -- claim \
+    --provider local-file \
+    --artifact-root <artifact-root> \
+    --subject-id <subjectId> \
+    --branch <branch> \
+    --artifact-dir <artifact_dir> \
+    --actor-json <path>
+  ```
+
+  A non-zero exit (already claimed by a different actor) must not be silently retried or overwritten — treat it exactly like a `held`/`reclaimable` conflict and return to `### 3. Select Work` to reselect.
+
+Then, regardless of provider kind, re-fetch current state — re-fetch the GitHub issue via `gh issue view --json assignees,labels,comments` for `github` (the local-file record is already current on disk) — and call `assignment-provider status` again, passing the same pinned `self_actor`, to **confirm** the claim landed before treating `selected_item_ids` as final:
+
+```bash
+npm run assignment-provider -- status --provider <github|local-file> --subject-id <subjectId> --self-actor <self_actor> ...
+```
+
+Confirm `effective.effective_state === "held"` with `effective.reason === "self_is_holder"` (the join function's signal that this session's own actor is the confirmed holder). Only after this confirmation does `selected_item_ids` become final for handoff. If confirmation fails — the claim did not land, or a different actor's record now appears — treat this exactly like a liveness double-hold: do not proceed to `plan-work` with this subject; return to `### 3. Select Work` to reselect, excluding the contested subject.
+
+Record the render/status evidence — provider kind, subject id, actor, the rendered/executed command(s), and the confirmed `status()` result — for every selected item under `selection` and in the dedicated `assignment_claim` artifact field (see Artifact Contract above).
+
 ### 4. Anchor Check
 
 Before planning, restate:
@@ -298,11 +441,11 @@ When the Pickup Gate passes and work is selected (not just a shepherding scan or
 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
-npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
   --expectation selected-work \
   --status pass \
   --summary "Selected <work-item-ref>: scope clear, acceptance criteria present." \
-  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact with selected_item_ids, scope, and acceptance criteria."}'
+  --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."}'
 ```
 
 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).

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

@@ -28,7 +28,7 @@ Release Readiness is not Evidence Gate. Evidence Gate decides whether completed
 
 ## Artifact Contract
 
-Create or update `.flow-agents/<slug>/<slug>--release-readiness.md` with:
+Create or update `.kontourai/flow-agents/<slug>/<slug>--release-readiness.md` with:
 
 - `release_scope`: work included, excluded, issue/provider-change links
 - `evidence_reference`: evidence artifact, verdict, residual risks
@@ -37,13 +37,13 @@ Create or update `.flow-agents/<slug>/<slug>--release-readiness.md` with:
 - `rollback_plan`: trigger, steps, owner, expected recovery signal
 - `observability_plan`: metrics, logs, traces, alerts, dashboards
 - `post_deploy_checks`: checks, commands, URLs, timing, expected signals
-- `final_acceptance_docs`: long-lived docs updated, archived `.flow-agents/<slug>/` links, and deferred docs follow-ups
+- `final_acceptance_docs`: long-lived docs updated, archived `.kontourai/flow-agents/<slug>/` links, and deferred docs follow-ups
 - `decision`: MERGE, RELEASE, DEPLOY, HOLD, or ROLLBACK_REQUIRED
 
 When the repository provides `npm run workflow:sidecar --`, also write `release.json` with:
 
 ```bash
-npm run workflow:sidecar -- record-release .flow-agents/<slug> \
+npm run workflow:sidecar -- record-release .kontourai/flow-agents/<slug> \
   --decision merge \
   --scope "..." \
   --evidence-ref evidence.json \
@@ -108,7 +108,7 @@ When CI has passed and merge/release acceptance is clear, require a docs decisio
 
 - update long-lived docs with what changed, how to use it, and important why/how decisions; or
 - record why no durable docs are needed; and
-- link back to the archived `.flow-agents/<slug>/` plan/session artifact for implementation history.
+- link back to the archived `.kontourai/flow-agents/<slug>/` plan/session artifact for implementation history.
 
 ## Gates
 

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

@@ -48,7 +48,7 @@ If a fix is needed, report it as a finding. The orchestrator routes it back to e
 
 ## Input
 
-- Session file path in `.flow-agents/<slug>/` when available
+- Session file path in `.kontourai/flow-agents/<slug>/` when available
 - Plan artifact or implementation summary
 - Modified files from execution progress or `git diff --name-only`
 - Project standards, especially `context/code-review-standards.md` when present
@@ -85,6 +85,29 @@ package-registry behavior, update dependencies, or install scanners. If the
 required dependency review cannot run, record the dependency lane as
 `not_verified`.
 
+For multi-repo or cross-product work, dependency review must preserve the full
+scope. Before delegating, enumerate every affected repo/package-manager root and
+record one status per root:
+
+- `pass`: dependency review ran and found no blocking issue
+- `fail`: dependency review ran and found a blocking advisory, version, or
+  lockfile issue
+- `skip_no_manifest`: the root has no supported dependency manifest
+- `not_verified`: review could not run or the result is unavailable
+
+Do not narrow the dependency lane to only roots that failed build/test. If the
+work changed shared conventions, generated artifact paths, install scripts, CI,
+or workspace-wide guidance, the dependency review summary must say which product
+roots were included and which were out of scope.
+
+External advisory/audit services can disclose private dependency metadata. Before
+running tools such as `npm audit`, registry lookups, or vendor advisory APIs,
+record whether the user explicitly approved that disclosure for the affected
+roots. If approval is absent, rejected, or too ambiguous for the local execution
+policy, keep local inventory evidence and mark the external-audit portion
+`not_verified` with the approval/privacy blocker. Do not convert that blocker
+into a clean pass.
+
 ## IaC/Policy Review Triggers
 
 Run security and configured IaC/policy review when modified files touch

package/kits/builder/skills/tdd-workflow/SKILL.md

@@ -137,4 +137,6 @@ coverage_target: 80
 - iteration 1: RED ✓, GREEN ✓, REFACTOR ✓, coverage 85%
 ```
 
+`<branch>` is the branch recorded in `state.json`'s `branch` field (`ensure-session` derives `agent/<actor>/<slug>`; an explicit `--branch` flag overrides on a new session). `ensure-session` only records the name — creating and checking out the actual git branch/worktree remains this skill's responsibility.
+
 {context?}