@kontourai/flow-agents 2.2.0 → 2.4.0

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

@@ -29,14 +29,17 @@ 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|free|mine, holder_actor?, status_raw}` plus `self_actor`/`self_actor_source`, computed via `liveness status --json` + `liveness whoami --json`; `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 the liveness-only projection of ADR 0021 §1's join, pending #290's assignment dimension
+- `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
 - `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 +114,41 @@ 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) and classify in this precedence order, reading each row's raw `status` field (never `label`):
+
+1. a `verified` row for an actor other than self ⇒ `held`, excluded from the ready set by default, even when a `verified` row for the resolved self actor also exists on the same subject — that combination 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`.
+2. else, a `verified` row for the resolved self actor ⇒ `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.
+3. else, a `stale` row (any actor) ⇒ `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.
+4. else (a `revoked`-only row, a `superseded` row, or no row at all) ⇒ `free`, offered normally — except a `superseded` row is surfaced but never auto-selected (full takeover semantics are #294; this is an accepted gap, not silently ignored).
+
+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`).
+
+This preflight computes the **liveness-only** projection of ADR 0021 §1's `assignment ⋈ liveness` join. The assignment dimension is #290's `AssignmentProvider` (durable GitHub-side claim); until it lands, assignment is treated as always-unassigned, which ADR 0021 §1's own table shows is safe because staleness — not assignment — is what excludes.
+
+`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 existing no-provider-mutation rule (see below) is unchanged by this slice. #290 will add the one narrow, audited GitHub-side mutation that pairs with this liveness emit.
+
 ### 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 +157,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 +225,43 @@ 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. True mutual exclusion arrives with the provider assignment lease (#290) and the `verify-hold` publish gate (#293).
+
 ### 4. Anchor Check
 
 Before planning, restate:
@@ -298,11 +373,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?}

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

@@ -39,7 +39,7 @@ This skill owns orchestration and routing. The verification contract owns phases
 
 ## Input
 
-- **Session file path**: the session file in `.flow-agents/<slug>/` (preferred)
+- **Session file path**: the session file in `.kontourai/flow-agents/<slug>/` (preferred)
 - The session file references the plan artifact (which has acceptance criteria) and execution progress (which has modified files)
 - If NO session file exists, delegate to tool-verifier directly (see Standalone Verification below)
 
@@ -84,6 +84,13 @@ Skip session file lookup — go straight to delegation.
 7. Write or update `evidence.json` with verification checks, top-level verdict, and `not_verified_gaps`
    - use `npm run workflow:sidecar -- record-evidence <artifact-dir> --verdict ... --check-json ...` when the repository provides it
    - `checks[].artifact_refs` must use structured evidence ref objects, not legacy strings
+   - for multi-repo or cross-product work, preserve a coverage matrix in the
+     evidence report or check summaries that lists each affected root and its
+     build/test, dependency/security, provider/CI, and accepted-gap status
+   - if external dependency audit or provider checks are blocked by approval,
+     privacy, credentials, network, or missing change-provider state, record the
+     affected roots as `not_verified` instead of collapsing the lane into a
+     generic pass/fail
 8. Update `acceptance.json` with criterion statuses and structured evidence refs
    - `criteria[].evidence_refs` must use structured evidence refs and map each AC id to command/test proof plus source refs for behavior claims
    - when source refs are missing for a behavior claim, mark the criterion `not_verified` or record an accepted gap instead of using broad prose-only evidence

package/kits/catalog.json

@@ -18,6 +18,12 @@
       "name": "Release Evidence Kit",
       "path": "kits/release-evidence",
       "description": "Minimal flows-only kit for proving agentless gate evaluation over surface claims in CI. One gate expects a trusted release.evidence claim."
+    },
+    {
+      "id": "veritas-governance",
+      "name": "Veritas Governance Kit",
+      "path": "kits/veritas-governance",
+      "description": "Agentless kit that gates a real `veritas readiness` verdict as a trust.bundle software-readiness-verdict claim. Wraps @kontourai/veritas via CLI + a kit-local adapter; does not reimplement standards evaluation."
     }
   ]
 }