@kontourai/flow-agents 3.0.0 → 3.2.0

package/build/src/lib/flow-resolver.d.ts

@@ -72,16 +72,22 @@ export declare function resolvePhaseMap(flowId: string, repoRoot: string): Recor
 /**
  * Resolve the active flow step from current.json.
  *
- * Reads active_flow_id and active_step_id from <flowAgentsDir>/current.json.
- * If both are present, delegates to resolveFlowStep. The repoRoot is derived by
- * walking upward from flowAgentsDir to find the nearest ancestor containing kits/,
- * with a fallback to process.cwd(). This handles temp dirs, CI workspaces, and
- * subproject layouts without hardcoding the repo structure.
+ * Reads active_flow_id and active_step_id via the shared per-actor current-pointer helper
+ * (#291 Wave 2 Task 2.2): when `actorKey` is a resolved actor with its own
+ * `current/<actor>.json` projection, that file is preferred; otherwise (no actorKey, an
+ * unresolved actor, or no per-actor file yet) this falls straight back to the legacy global
+ * `<flowAgentsDir>/current.json` — IDENTICAL to this function's pre-#291 behavior for every
+ * caller that does not pass `actorKey`. The repoRoot is derived by walking upward from
+ * flowAgentsDir to find the nearest ancestor containing kits/, with a fallback to
+ * process.cwd(). This handles temp dirs, CI workspaces, and subproject layouts without
+ * hardcoding the repo structure.
  *
  * @param flowAgentsDir Path to the runtime artifact root directory (contains current.json).
+ * @param actorKey Optional resolved actor identity (Wave 2 Task 2.1's `writeCurrent()` dual-write
+ *   key) — when omitted, behavior is unchanged (legacy-file-only, exactly as before #291).
  * @returns ActiveFlowStep or null when fields are absent or resolution fails.
  */
-export declare function resolveActiveFlowStep(flowAgentsDir: string): ActiveFlowStep | null;
+export declare function resolveActiveFlowStep(flowAgentsDir: string, actorKey?: string): ActiveFlowStep | null;
 /** The resolved route-back policy for a phase transition. */
 export type RouteBackPolicy = {
     /** Maximum allowed route-back attempts for this transition key. */

package/build/src/lib/flow-resolver.js

@@ -14,6 +14,8 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 // ─── Security: Layer 1 traversal defense ─────────────────────────────────────
 //
 // Both kitId and flowName originate from agent-writable sources (active_flow_id
@@ -270,30 +272,44 @@ function findRepoRoot(startDir) {
     // Fallback: process.cwd() covers the common "run from repo root" case
     return process.cwd();
 }
+/**
+ * Delegate to the shared pure-CJS per-actor current-pointer reader
+ * (scripts/hooks/lib/current-pointer.js), mirroring the exact createRequire idiom
+ * workflow-sidecar.ts already uses for its own cross-boundary CJS helper reuse (Wave 2 Task 2.2,
+ * #291). Deliberately NO inline duplicate fallback — this is the single choke point for the
+ * per-actor-first/legacy-fallback compat-shim rule; a second hand-rolled reader here would let it
+ * drift from every other consumer.
+ */
+function loadCurrentPointerHelper() {
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/current-pointer.js");
+    return _req(helperPath);
+}
 /**
  * Resolve the active flow step from current.json.
  *
- * Reads active_flow_id and active_step_id from <flowAgentsDir>/current.json.
- * If both are present, delegates to resolveFlowStep. The repoRoot is derived by
- * walking upward from flowAgentsDir to find the nearest ancestor containing kits/,
- * with a fallback to process.cwd(). This handles temp dirs, CI workspaces, and
- * subproject layouts without hardcoding the repo structure.
+ * Reads active_flow_id and active_step_id via the shared per-actor current-pointer helper
+ * (#291 Wave 2 Task 2.2): when `actorKey` is a resolved actor with its own
+ * `current/<actor>.json` projection, that file is preferred; otherwise (no actorKey, an
+ * unresolved actor, or no per-actor file yet) this falls straight back to the legacy global
+ * `<flowAgentsDir>/current.json` — IDENTICAL to this function's pre-#291 behavior for every
+ * caller that does not pass `actorKey`. The repoRoot is derived by walking upward from
+ * flowAgentsDir to find the nearest ancestor containing kits/, with a fallback to
+ * process.cwd(). This handles temp dirs, CI workspaces, and subproject layouts without
+ * hardcoding the repo structure.
  *
  * @param flowAgentsDir Path to the runtime artifact root directory (contains current.json).
+ * @param actorKey Optional resolved actor identity (Wave 2 Task 2.1's `writeCurrent()` dual-write
+ *   key) — when omitted, behavior is unchanged (legacy-file-only, exactly as before #291).
  * @returns ActiveFlowStep or null when fields are absent or resolution fails.
  */
-export function resolveActiveFlowStep(flowAgentsDir) {
+export function resolveActiveFlowStep(flowAgentsDir, actorKey) {
     if (!flowAgentsDir)
         return null;
-    const currentFile = path.join(flowAgentsDir, "current.json");
-    let current;
-    try {
-        const raw = fs.readFileSync(currentFile, "utf8");
-        current = JSON.parse(raw);
-    }
-    catch {
+    const pointer = loadCurrentPointerHelper().readCurrentPointer(flowAgentsDir, actorKey);
+    if (pointer.source === "none" || !pointer.payload)
         return null;
-    }
+    const current = pointer.payload;
     const flowId = typeof current["active_flow_id"] === "string" ? current["active_flow_id"] : null;
     const stepId = typeof current["active_step_id"] === "string" ? current["active_step_id"] : null;
     if (!flowId || !stepId)

package/build/src/tools/validate-source-tree.js

@@ -83,6 +83,7 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/lib/actor-identity.js", { category: "shared hook library", requiredNeedles: ["resolveActor", "FLOW_AGENTS_ACTOR"] }],
     ["scripts/hooks/lib/audit-transport.sh", { category: "shared hook library", requiredNeedles: ["audit_emit"] }],
     ["scripts/hooks/lib/config-protection-remedies.js", { category: "shared hook library", requiredNeedles: ["SANCTIONED_REMEDIES", "REMEDY_COMMAND_CANDIDATES"] }],
+    ["scripts/hooks/lib/current-pointer.js", { category: "shared hook library", requiredNeedles: ["readCurrentPointer", "perActorCurrentFile"] }],
     ["scripts/hooks/lib/hook-flags.js", { category: "shared hook library", requiredNeedles: ["isHookEnabled"] }],
     ["scripts/hooks/lib/liveness-heartbeat.js", { category: "shared hook library", requiredNeedles: ["maybeEmitHeartbeat", "resolveHeartbeatThrottleSeconds"] }],
     ["scripts/hooks/lib/liveness-policy.js", { category: "shared hook library", requiredNeedles: ["isLivenessEnabled", "resolveTtlSeconds"] }],
@@ -93,7 +94,7 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/lib/resolve-formatter.js", { category: "shared hook library", requiredNeedles: ["resolveFormatter"] }],
 ]);
 const fixtureOwnerPolicies = new Map([
-    ["evals/fixtures/assignment-provider", { owners: ["evals/integration/test_assignment_provider_local_file.sh", "evals/integration/test_assignment_provider_github.sh", "evals/integration/test_pull_work_assignment_join.sh"], classification: "AssignmentProvider local-file and GitHub render/status fixtures (#290)" }],
+    ["evals/fixtures/assignment-provider", { owners: ["evals/integration/test_assignment_provider_local_file.sh", "evals/integration/test_assignment_provider_github.sh", "evals/integration/test_pull_work_assignment_join.sh", "evals/integration/test_ensure_session_ownership_guard.sh"], classification: "AssignmentProvider local-file and GitHub render/status fixtures (#290); hostile-effective-state.json is the #291 ensure-session ownership guard's AC9 sanitization fixture" }],
     ["evals/fixtures/backlog-provider-settings", { owners: ["evals/integration/test_effective_backlog_settings.sh"], classification: "settings precedence fixtures" }],
     ["evals/fixtures/builder-kit-workflow-state", { owners: ["evals/static/test_workflow_skills.sh"], classification: "Builder Kit workflow-state fixtures" }],
     ["evals/fixtures/console-learning-projection", { owners: ["evals/integration/test_console_learning_projection.sh"], classification: "console learning projection fixtures" }],

package/context/contracts/assignment-provider-contract.md

@@ -93,10 +93,18 @@ delivers all four:
 | Transition | Mutator | When | Owning issue |
 | --- | --- | --- | --- |
 | `claim` | the claiming session | at selection | **#290 (this issue)** |
-| `clean_release` | the incumbent (Stop hook / terminal `advance-state`) | session end — unassign + handoff comment | #292 |
+| `claim` / `supersede` | `ensure-session`'s pre-entry ownership guard (a SECOND mutator, alongside `assignment-provider claim`) | on session entry, before any session directory is created — `free` establishes a claim, `reclaimable` requires explicit `--supersede-stale` | **#291** |
+| `clean_release` | the incumbent (Stop hook / terminal `advance-state`) | session end — unassign + handoff comment | **#292** — the Stop hook (`scripts/hooks/stop-goal-fit.js`) on clean non-terminal session end: liveness release + local-file assignment release (`performLocalRelease`) run inline; for the github provider the hook cannot run `gh`, so it honestly defers via a `provider_release_pending` handoff intent rather than pretending to complete the release |
 | `supersede` | the successor, inside the takeover protocol | after the grace beat | #294 |
 | `crash_no_successor` | nobody, initially; corrected by the next actor to want the subject, or the janitor | lazily, or on a janitor sweep | out of scope — the Console relay's first cross-machine duty (ADR 0021 §4/§7) |
 
+`ensure-session`'s guard reuses this file's own `computeEffectiveState`/`performLocalClaim`/
+`performLocalSupersede` (Wave 1 exports) rather than a parallel implementation — see
+`docs/adr/0021-assignment-leases-and-stale-claim-takeover.md` §3 for why a second claim point
+was needed (a session entered without going through `pull-work` previously got no durable claim
+at all) and the canonical `actor_key` field (below) that keeps its self-recognition consistent
+with every other tool that reads or writes a claim record.
+
 Lazy correction is *safe* by the join rule above (stale assignment excludes nothing), but leaves
 the human-visible board stale in the crash case until the next claim attempt or a janitor sweep
 corrects it.
@@ -146,6 +154,7 @@ detect an incompatible future shape before parsing fields it does not understand
 | `role` | yes | Constant `"AssignmentClaimRecord"`, for readers scanning mixed content (e.g. a GitHub comment thread) for this record type. |
 | `subject_id` | yes | The claimed work item, in `owner/repo#id` form — the same string `workItemSlug` derives the deterministic session slug from. |
 | `actor` | yes | `{ runtime, session_id, host, human? }` — the exact struct `actor-identity.js` defines. `human` is set (non-null) only for a human assignee; its presence, not a username heuristic, gates the human-held join state. |
+| `actor_key` | no (additive, #291) | The canonical `resolveActor(env).actor` string for the claiming actor — the same flat/bare token `liveness whoami`, `liveness claim --actor`, per-actor `current.json`, and pull-work's `--self-actor` all use. When present, `computeEffectiveState` compares against THIS (not a re-serialization of `actor`) for both self-recognition and the liveness join, because `serializeActor(actor)` and `resolveActor(env).actor` diverge for an explicit-override actor (a bare token vs. a `explicit-override:<value>:<host>` triple) while agreeing for a derived actor. Absent on any pre-#291 record or fixture — `computeEffectiveState` falls back to `serializeActor(actor)` in that case, reproducing pre-#291 behavior exactly. |
 | `claimed_at` | yes | ISO-8601 timestamp the claim was recorded. Mirrors the liveness stream's own claim-event field so a reader compares freshness with one mental model across both layers, even though the two are stored in different media. |
 | `ttl_seconds` | yes | Same field name/semantics as the liveness stream's `ttlSeconds` (default `1800`). |
 | `branch` | yes | The branch this actor is working on, per the `agent/<actor>/<slug>` convention. |

package/context/contracts/execution-contract.md

@@ -67,6 +67,84 @@ model backs which delegate role. This contract only says where to read it.
   fallback in the session/task artifact — do not block delegation on datum
   being present.
 
+### Tier ladder
+
+The delegate roles form a cost/capability ladder that both escalation and the
+Goodhart guard below reference. Lowest to highest:
+
+```
+delegate-mechanical  <  delegate-implementation  <  delegate-design
+```
+
+`orchestrator` is off-ladder — it is the session's own model (planning, gates,
+adversarial verification), typically inherited rather than overridden, and sits
+above `delegate-design` for escalation purposes. `extraction-default` is a
+non-delegate role (bulk extraction) and is not part of this ladder.
+
+### Escalation on gate failure
+
+Delegate at the step's hinted tier, then let the gates enforce cost safety:
+
+- Dispatch the delegate at the tier its skill hint names (a cheap tier for
+  mechanical/fully-specified work).
+- On a review or verify **gate FAILURE of that delegate's output**, re-dispatch
+  the **fix** one tier higher on the ladder — `delegate-mechanical` failures
+  escalate to `delegate-implementation`, `delegate-implementation` failures to
+  `delegate-design`, and a `delegate-design` failure escalates to the
+  `orchestrator` / a human decision. Do not re-dispatch the fix at the same
+  tier that already failed its gate.
+- Record every escalation in the session artifact (see *Routing decisions in
+  the run artifact* below) with the tier it climbed **from**, so the run shows
+  why a more expensive model was used.
+- This is the fail-closed cost story: cheap tiers are safe **because** the gates
+  catch their misses and escalate. Routing cheap-by-default never weakens
+  verification — an ungated cheap delegate is what this ladder exists to prevent.
+
+### Goodhart guard (review/verify never cheaper than the work)
+
+Review and verify roles resolve at a tier **greater than or equal to** the tier
+of the work they check; they never auto-downgrade below it.
+
+- If the checked work was produced at `delegate-design`, its reviewer/verifier
+  resolves `delegate-design` (or `orchestrator`) — never `delegate-implementation`
+  or `delegate-mechanical`.
+- If the checked work was produced at `delegate-implementation`, its
+  reviewer/verifier resolves at `delegate-implementation` or higher.
+- Rationale: a cheaper checker rubber-stamping a more capable worker's output
+  defeats the gate and turns the routing table into a Goodhart target (optimize
+  the cost metric, lose the thing the metric was a proxy for). The gate must be
+  at least as capable as the work, or the fail-closed escalation story above is
+  hollow.
+
+### Routing decisions in the run artifact
+
+Record each delegation's resolved role and model on the session artifact so a
+downstream economics record (`flow-agents#349`) can price role assignments and a
+baseline harness (`flow-agents#350`) can A/B tiers. Use the sidecar writer's
+`record-agent-event` (additive `--role` / `--model` / `--escalated-from` flags):
+
+```bash
+# per-delegation routing decision
+npm run workflow:sidecar -- record-agent-event \
+  --agent-id <delegate-id> --kind delegation --status active \
+  --role <resolved-role> --model "<resolved-model@provider>" \
+  --summary "<what was delegated>"
+
+# an escalate-on-gate-failure re-dispatch
+npm run workflow:sidecar -- record-agent-event \
+  --agent-id <delegate-id> --kind escalation --status active \
+  --role <higher-tier-role> --model "<resolved-model@provider>" \
+  --escalated-from <lower-tier-role> \
+  --summary "<gate that failed> failed at <lower-tier-role>; fix re-dispatched one tier higher"
+```
+
+These land as top-level `role`, `model`, and (for escalations) `escalated_from`
+fields on the JSONL event under `agents/<agent-id>/events.jsonl`. The shape is
+additive: events without a routing decision are byte-identical to before, so no
+existing consumer breaks. An economics consumer reads events where `role` is
+present as one priced delegation each; `escalated_from` marks the entries that
+cost more because a gate caught a cheaper tier.
+
 ## Completion Rules
 
 Execution is complete only when:

package/context/contracts/probe-docs-write-contract.md

@@ -0,0 +1,187 @@
+# Probe Docs-Write Contract
+
+> Read [`context/contracts/standing-directives.md`](standing-directives.md) — ratified owner directives that override default engineering conservatism.
+
+Normative contract for how a Probe (`design-probe`, and its Builder Kit
+`pickup-probe` specialization) writes durable documentation as understanding
+crystallizes during probing. This is the docs-write half of the grill-with-docs
+pattern: a Probe already interviews and aligns; this contract says what a Probe
+must leave behind in durable docs, not just in the session artifact.
+
+## Why
+
+Probe outcomes previously landed only in session artifacts (`.kontourai/flow-agents/<slug>/`):
+vocabulary and decisions crystallized while probing had to be re-extracted later,
+or were lost when the session archived. Grill-with-docs' whole point is that the
+interview leaves living documentation behind, not session-local notes. This
+contract makes that the default behavior for every Probe, not an occasional
+manual follow-up.
+
+## Scope
+
+Applies to `design-probe` (generic) and `pickup-probe` (the Builder Kit
+pickup specialization) — see
+[`kits/builder/skills/design-probe/SKILL.md`](../../kits/builder/skills/design-probe/SKILL.md)
+and
+[`kits/builder/skills/pickup-probe/SKILL.md`](../../kits/builder/skills/pickup-probe/SKILL.md).
+It does not create a new skill; both existing Probe skills already own the
+grill/grill-with-docs behavior (R1 in
+[flow-agents#311](https://github.com/kontourai/flow-agents/issues/311)) — this
+contract only normalizes what they write and where.
+
+Out of scope: enforcement gating on Probe docs-writes (a separate issue),
+`CONTEXT.md` restructuring beyond vocabulary sections, and repositories with no
+`CONTEXT.md` (an open question the owner has not settled; non-blocking for
+flow-agents, which always has one).
+
+## The Two-Delta Rule
+
+**Per crystallized understanding** — a question the Probe asked and the user (or
+discoverable local evidence) definitively answered, not a still-open question or
+an accepted gap — the Probe emits, in the same motion:
+
+1. **A vocabulary delta** into `CONTEXT.md` (or the owning `CONTEXT-MAP.md`
+   context when one exists) — see [Vocabulary Delta](#1-vocabulary-delta-coin-first).
+2. **A decision delta** into `docs/decisions/<slug>.md` — see
+   [Decision Delta](#2-decision-delta-retrieval-at-write).
+3. **Transcript provenance** — the decision delta's `evidence[]` links the
+   session artifact that produced it — see
+   [Transcript Provenance](#3-transcript-provenance).
+
+Not every Probe question needs both deltas. A question resolved by reading
+existing docs/code needs neither (nothing crystallized — it was already
+decided). A question about implementation detail, sequencing, or a transient
+planning choice needs neither (it belongs in the workflow artifact, per
+`context/contracts/artifact-contract.md`, not durable docs). The two-delta rule
+applies specifically to a **decision subject** crystallizing: a durable,
+reusable answer to a named domain question that other work will need to look up
+later. If in doubt, ask: "will a future session need to know this answer without
+re-deriving it?" — if yes, it is a decision subject and both deltas apply.
+
+### 1. Vocabulary delta (coin-first)
+
+**A decision subject may only use subject terms present in (or added to)
+`CONTEXT.md` in the same session** (R2). Vocabulary is the topic namespace the
+decision registry's slugs are drawn from
+(`context/contracts/decision-registry-contract.md` § Slug rules), so the term
+must exist before the topic file can be named.
+
+- If the crystallized understanding's subject noun is **already** a `CONTEXT.md`
+  glossary term, the vocabulary delta may be a **refinement** of that entry
+  rather than a new one — e.g. removing "subject open" language once a decision
+  ratifies it, tightening a definition, or adding an `_Avoid_` term. This still
+  counts as a vocabulary delta: the glossary is a living document, not
+  write-once.
+- If the subject noun is **absent**, **coin it first**: add a tight one- or
+  two-sentence `### <Term>` entry to `CONTEXT.md`'s Glossary section, in the
+  same style as existing entries (definition, optional `_Avoid_` line). Do this
+  before creating the decision file — the term is the slug's namespace, not an
+  afterthought.
+- Keep the vocabulary delta to glossary-style terminology. Implementation
+  detail, rationale, and derivation stay out of `CONTEXT.md` (unchanged from the
+  Probe skills' existing docs discipline).
+- If a `CONTEXT-MAP.md` exists and a more specific context owns the term, update
+  that context instead of assuming the root glossary owns every term.
+
+### 2. Decision delta (retrieval-at-write)
+
+Once the vocabulary exists, record the decision per
+`context/contracts/decision-registry-contract.md` in full — this contract does
+not repeat the frontmatter/slug/tombstone rules, only the Probe-specific
+sequencing:
+
+1. **Consult `docs/decisions/index.md`** (the always-loaded slug + one-liner
+   index) before writing anything, and propose **revise-vs-create**:
+   - An existing topic slug already covers the subject (including a
+     `needs-decision` stub seeded by ADR-freeze tooling, issue #314) → **revise
+     that file in place.** Flip `needs-decision` → `current` (or edit a `current`
+     file's body/`decided` date for a superseding decision), add the new
+     `evidence[]` refs, do not create a second file for the same subject.
+   - No topic covers the subject → confirm the vocabulary delta above landed,
+     then **create** `docs/decisions/<slug>.md` with the frontmatter shape
+     `context/contracts/decision-registry-contract.md` defines.
+2. Run `npm run gen:decisions-index && npm run check:decisions` after every
+   decision-delta write. A Probe session is not done touching the registry until
+   both exit 0.
+3. Never propose a numbered ADR. `docs/adr/` is frozen history
+   (`docs/adr/README.md`); a Probe's decision delta always targets the
+   topic-keyed registry, never a new `docs/adr/NNNN-*.md` file.
+
+### 3. Transcript provenance
+
+Every decision file a Probe creates or edits carries an `evidence[]` entry of
+`kind: session-archive` pointing at the Probe's own session artifact (R3) — the
+Markdown file recording the interview, decisions, and accepted gaps
+(`.kontourai/flow-agents/<slug>/<slug>--design-probe.md`,
+`<slug>--pull-work.md`, or the equivalent Probe record the active workflow
+artifact uses).
+
+- Record the **live session path** at write time, even though the topic file
+  and the decision-registry contract describe `session-archive` as pointing at
+  an *archived* artifact "promoted at retirement" — the Probe runs at shaping
+  time, before the session archives. This is a deliberate, documented seam: the
+  promote-then-archive gate (issue #312) is the retirement-time mechanism that
+  moves the session directory to `<artifact-root>/archive/<slug>/` and is
+  responsible for keeping already-written evidence refs accurate across that
+  move. The Probe's job is emitting the initial link, not the later archival
+  move; do not block a decision delta on the session having archived first.
+- When the Probe is also citing a frozen ADR as prior provenance (e.g. upgrading
+  a `needs-decision` stub whose `evidence[]` already names one), keep that `adr`
+  evidence entry and add the `session-archive` entry alongside it — provenance
+  accumulates, it does not replace.
+- Also add a `pr`/`issue` evidence entry once a PR or issue number exists for the
+  work, following the same pattern every other decision file in the registry
+  uses.
+
+## Worked Example: Upgrading a Needs-Decision Stub
+
+The ADR-freeze cutover (issue #314, landed in #368) seeded 17 `needs-decision`
+stubs, each naming a subject with provenance in a frozen ADR but no ratified
+living decision. These are the natural first targets for this contract: a Probe
+that settles one of these subjects from existing evidence (the frozen ADR
+already states a decision that remains true — nothing new needs deciding, only
+recording) does the following:
+
+1. **Read the stub** (`docs/decisions/<slug>.md`, `status: needs-decision`) and
+   its `evidence[]`-linked frozen ADR(s).
+2. **Vocabulary delta**: the subject noun is already a `CONTEXT.md` term (seeded
+   alongside the stub during the freeze cutover) — refine its definition to
+   state the decision is now living rather than "subject open in the Decision
+   Registry," and keep the link to `docs/decisions/<slug>.md`.
+3. **Decision delta**: consult `docs/decisions/index.md` — the slug already
+   exists (revise, not create). Edit `docs/decisions/<slug>.md`:
+   `status: needs-decision` → `current`, set `decided` to today, keep the
+   existing `adr` evidence ref(s), append a `session-archive` ref (this Probe's
+   session artifact) and a `pr` ref once the PR exists, and write the `# <Title>`
+   body stating the decision (drawn from the ADR) plus lean rationale.
+4. Run `npm run gen:decisions-index && npm run check:decisions`; both must exit
+   0 before the Probe records the gate claim.
+5. **Transcript provenance**: the session-archive evidence ref from step 3 is the
+   provenance link (R3).
+
+This exercises all three rules end-to-end without inventing a new decision —
+the frozen ADR already made the call; the Probe's job is only recording that it
+is still true and giving it a living home.
+
+## Relationship To Other Contracts
+
+- **`context/contracts/decision-registry-contract.md`** is the normative
+  frontmatter/slug/tombstone/validation contract for every `docs/decisions/`
+  file, Probe-written or not. This contract only adds *when* and *in what
+  sequence* a Probe writes to that registry.
+- **`context/contracts/artifact-contract.md`** governs the Probe's session
+  artifact itself (the thing this contract's transcript-provenance rule links
+  to) and the promote/archive lifecycle referenced above.
+- **`docs/adr/README.md`** is where this contract is announced as the mechanism
+  that supersedes the prior "propose ADRs sparingly" Probe guidance — Probes
+  never write numbered ADRs; they write decision-registry deltas.
+
+## Validation
+
+- `npm run check:decisions` / `npm run gen:decisions-index` — the decision
+  delta must pass the registry validator and keep the index current (wired into
+  the required `source-and-static` CI lane).
+- `evals/static/test_workflow_skills.sh` — asserts `design-probe` and
+  `pickup-probe` reference this contract and describe the two-delta behavior.
+- `evals/static/test_decisions.sh` — regression coverage for the validator and
+  generator this contract's decision deltas depend on.

package/context/scripts/hooks/config-protection.js

@@ -131,6 +131,18 @@ function checkProtectedPathPattern(filePath) {
     };
   }
 
+  // .kontourai/flow-agents/current/<actor>.json (#291) — the per-actor projection of the same
+  // pointer above. An agent could forge active_flow_id/active_step_id here exactly as it could
+  // via the legacy global file, so this is protected identically (same reason text).
+  // SAFE: the workflow CLI writes this via writePerActorCurrent → fs.writeFileSync,
+  // NOT via the Write/Edit tool — blocking the tool path does not break legit sidecar.
+  if (/(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$/.test(norm)) {
+    return {
+      name: '.kontourai/flow-agents/current/<actor>.json',
+      reason: 'an agent could forge active_flow_id/active_step_id to route the gate to a permissive FlowDefinition',
+    };
+  }
+
   // .kontourai/flow-agents/.goal-fit-block-streak.json controls soft-block
   // release counting. An agent could force early advisory-gate release by
   // writing a high count.
@@ -168,7 +180,9 @@ function checkProtectedPathPattern(filePath) {
   // copy a forged bundle here to corrupt the CI trust check.
   // SAFE: publishDelivery writes via fs.copyFileSync (not Write/Edit tool).
   // RESIDUAL: runtime-constructed paths and fs writes are unaffected.
-  if (/(?:^|\/)delivery\/trust\.bundle$/.test(norm)) {
+  // #379: the optional (?:[^/]+\/)? segment also covers the per-session path
+  // delivery/<slug>/trust.bundle — the forgery surface moved with the write path.
+  if (/(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$/.test(norm)) {
     return {
       name: "delivery/trust.bundle",
       reason: "an agent could write a forged bundle to corrupt the CI trust-reconcile anchor",
@@ -177,7 +191,8 @@ function checkProtectedPathPattern(filePath) {
 
   // delivery/trust.checkpoint.json -- the signed checkpoint companion.
   // SAFE: publishDelivery writes via fs.copyFileSync, NOT via Write/Edit tool.
-  if (/(?:^|\/)delivery\/trust\.checkpoint\.json$/.test(norm)) {
+  // #379: optional (?:[^/]+\/)? segment also covers delivery/<slug>/trust.checkpoint.json.
+  if (/(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/.test(norm)) {
     return {
       name: "delivery/trust.checkpoint.json",
       reason: "an agent could forge a signed delivery by writing a tampered checkpoint",
@@ -403,12 +418,15 @@ function checkCommandForBypass(command) {
  * Regex that matches a normalized (forward-slash) path ending with a protected
  * kill-switch file: shell profiles, .claude/settings*.json,
  * .kontourai/flow-agents/current.json,
+ * .kontourai/flow-agents/current/<actor>.json (#291 per-actor projection),
  * .kontourai/flow-agents/.goal-fit-block-streak.json,
  * .kontourai/flow-agents/<slug>/state.json,
  * .kontourai/flow-agents/<slug>/trust.bundle, and deprecated runtime-shaped
  * .flow-agents equivalents.
  */
-const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
+// #379: the delivery/ arms carry an optional (?:[^/]+\/)? segment so redirects/tee to the
+// per-session path delivery/<slug>/trust.bundle (+ checkpoint) are caught, not just the flat path.
+const REDIRECT_PROTECTED_RE = /(?:^|\/|~\/)(\.bash_profile|\.bashrc|\.profile|\.zprofile|\.zshrc)$|(?:^|\/)\.claude\/settings(?:\.local)?\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/current\/[^/]+\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/\.goal-fit-block-streak\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/state\.json$|(?:^|\/)(?:\.kontourai\/flow-agents|\.flow-agents)\/[^/]+\/trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/;
 
 /**
  * Return true when a token (an unquoted redirect target or tee argument) matches
@@ -556,8 +574,10 @@ function checkInterpreterWriteToProtected(command) {
  * Delivery-protected path regex: delivery/trust.bundle and delivery/trust.checkpoint.json.
  * These are the CI anchor files whose contents must not be agent-forged.
  * Used by checkCopyMoveToProtected to catch `cp x delivery/trust.bundle`.
+ * #379: the optional (?:[^/]+\/)? segment also catches the per-session path
+ * `cp forged.json delivery/<slug>/trust.bundle`.
  */
-const DELIVERY_COPY_PROTECTED_RE = /(?:^|\/)delivery\/trust\.bundle$|(?:^|\/)delivery\/trust\.checkpoint\.json$/;
+const DELIVERY_COPY_PROTECTED_RE = /(?:^|\/)delivery\/(?:[^/]+\/)?trust\.bundle$|(?:^|\/)delivery\/(?:[^/]+\/)?trust\.checkpoint\.json$/;
 
 /**
  * Return true when a normalized token matches a delivery-protected path.

package/context/scripts/hooks/lib/config-protection-remedies.js

@@ -22,6 +22,8 @@ const SANCTIONED_REMEDIES = {
     'There is no sanctioned automated writer for this file. Ask a human maintainer to edit it directly. Never disable this hook to make the write.',
   '.kontourai/flow-agents/current.json':
     'Use `npm run workflow:sidecar -- ensure-session` (or `advance-state`), which writes this file for you. Never disable this hook to make the write.',
+  '.kontourai/flow-agents/current/<actor>.json':
+    'Use `npm run workflow:sidecar -- ensure-session` (or `advance-state`), which writes this file for you. Never disable this hook to make the write.',
   '.kontourai/flow-agents/.goal-fit-block-streak.json':
     'This file is only mutated internally by the goal-fit Stop hook; there is no sanctioned agent writer. Never disable this hook to make the write.',
   '.kontourai/flow-agents/<slug>/state.json':
@@ -61,6 +63,13 @@ const REMEDY_COMMAND_CANDIDATES = [
   { name: '.kontourai/flow-agents/<slug>/trust.bundle', needles: ['trust.bundle'] },
   { name: '.kontourai/flow-agents/<slug>/state.json', needles: ['state.json'] },
   { name: '.kontourai/flow-agents/.goal-fit-block-streak.json', needles: ['.goal-fit-block-streak.json'] },
+  // #291: the per-actor projection (current/<actor>.json) is checked BEFORE the legacy
+  // current.json needle below — its needle is a directory-scoped substring
+  // ('flow-agents/current/') that never overlaps with the bare 'current.json' basename, so
+  // ordering between these two entries has no effect on real inputs, but keeping the more
+  // specific per-actor entry first mirrors this table's existing "specific before generic"
+  // convention.
+  { name: '.kontourai/flow-agents/current/<actor>.json', needles: ['flow-agents/current/', '.flow-agents/current/'] },
   { name: '.kontourai/flow-agents/current.json', needles: ['current.json'] },
   { name: '.claude/settings.local.json', needles: ['settings.local.json'] },
   { name: '.claude/settings.json', needles: ['.claude/settings.json'] },