@kontourai/flow-agents 3.0.0 → 3.2.0

package/context/scripts/hooks/stop-goal-fit.js

@@ -25,6 +25,7 @@
 'use strict';
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const crypto = require('crypto');
@@ -42,6 +43,8 @@ const {
   flowAgentsArtifactRoot,
   flowAgentsArtifactRootsForRead,
 } = require('./lib/local-artifact-paths');
+const { resolveActor, isUnresolvedActor, detectRuntime } = require('./lib/actor-identity.js');
+const { readCurrentPointer } = require('./lib/current-pointer.js');
 
 const MAX_STDIN = 1024 * 1024;
 const ACTIVE_STATUSES = new Set([
@@ -1531,7 +1534,7 @@ async function bundleEnforcement(artifactDir, activeFlowStep) {
  * to scanning all of .kontourai/flow-agents (newest-mtime).
  */
 function preferredArtifactDir(flowAgentsDir) {
-  const current = readJsonFile(path.join(flowAgentsDir, 'current.json'));
+  const { payload: current } = readCurrentPointer(flowAgentsDir, resolveActor(process.env).actor);
   if (!current) return null;
   const slug = current.artifact_dir || current.active_slug;
   if (typeof slug !== 'string' || !slug.trim()) return null;
@@ -1549,7 +1552,7 @@ function hasSidecarPresence(artifactDir) {
 // return that slug so analyze() can log the staleness rather than silently falling back to
 // a global mtime scan that could resurface an abandoned/never-real session as active.
 function staleCurrentSlug(flowAgentsDir) {
-  const current = readJsonFile(path.join(flowAgentsDir, 'current.json'));
+  const { payload: current } = readCurrentPointer(flowAgentsDir, resolveActor(process.env).actor);
   if (!current) return null;
   const slug = current.artifact_dir || current.active_slug;
   if (typeof slug !== 'string' || !slug.trim()) return null;
@@ -1669,7 +1672,7 @@ async function analyze(root, now = Date.now()) {
     artifacts = artifacts.filter(a => a && hasSidecarPresence(path.dirname(a.file)));
   }
 
-  if (artifacts.length === 0) return { warnings: [], blocking: false };
+  if (artifacts.length === 0) return { warnings: [], blocking: false, latestArtifactDir: null };
 
   const latest = artifacts[0];
   const latestArtifactDir = path.dirname(latest.file);
@@ -1743,7 +1746,7 @@ async function analyze(root, now = Date.now()) {
     if (/\[backstop in warn mode — not blocking\]/.test(w)) return false;
     return blockRe.test(w);
   });
-  return { warnings, blocking, preExecution, gatePrefix: gateLabel(activeFlowStep) };
+  return { warnings, blocking, preExecution, gatePrefix: gateLabel(activeFlowStep), latestArtifactDir };
 }
 
 /**
@@ -1842,12 +1845,266 @@ function remediationFor(warning) {
   return null;
 }
 
+// ─── #292 Wave 2: Stop-hook non-terminal release-with-handoff ────────────────
+//
+// When a session's Stop event fires and the session's state.json status is NOT
+// one of workflow-sidecar.ts's LIVENESS_TERMINAL statuses (delivered/accepted/
+// archived — the SAME set advance-state's terminal path already tests against,
+// imported here rather than re-declared, per AC8), the liveness claim and (for
+// the local-file assignment provider) the durable assignment claim would
+// otherwise sit held until TTL, even though the session has genuinely ended.
+// This closes that gap: always emit a provider-agnostic liveness release (AC1),
+// and for local-file additionally perform the real release inline (AC2), while
+// honestly disclosing (never executing) the equivalent GitHub-provider release
+// as a pending handoff.json intent (AC3). See the plan artifact
+// (.kontourai/flow-agents/kontourai-flow-agents-292/kontourai-flow-agents-292--plan-work.md,
+// "Wave 2") for the full design rationale and the render-don't-execute
+// constraint this deliberately does not cross.
+//
+// Fail-open (AC7): the ENTIRE body runs under one try/catch. Any failure —
+// missing build/, corrupt assignment record, unresolved actor, missing/
+// malformed provider settings — degrades to a single stderr diagnostic and
+// returns, never throwing, never affecting the Stop hook's own exit code or
+// goal-fit's warnings/blocking output (this function's return value is not
+// consumed by that contract at all — it is a pure side effect).
+
+/**
+ * require() the compiled workflow-sidecar.js the same hasBuild/fs.existsSync-guarded
+ * way loadActiveFlowStep() already requires flow-resolver.js. Returns null (never
+ * throws) when build/ is absent or the require fails — the caller treats null as
+ * "the LIVENESS_TERMINAL boundary is unknown; do not guess it" and skips the whole
+ * release (fail-open, never a re-derived duplicate Set — AC8).
+ */
+function loadWorkflowSidecarBuilt() {
+  const packageRoot = path.resolve(__dirname, '..', '..');
+  const builtSidecar = path.join(packageRoot, 'build', 'src', 'cli', 'workflow-sidecar.js');
+  if (!fs.existsSync(builtSidecar)) return null; // hasBuild guard
+  try {
+    const mod = require(builtSidecar);
+    if (!(mod.LIVENESS_TERMINAL instanceof Set)) return null;
+    return mod;
+  } catch {
+    return null; // require failed — fail-open
+  }
+}
+
+/** Same hasBuild-guarded require idiom, for build/src/cli/assignment-provider.js. */
+function loadAssignmentProviderBuilt() {
+  const packageRoot = path.resolve(__dirname, '..', '..');
+  const builtProvider = path.join(packageRoot, 'build', 'src', 'cli', 'assignment-provider.js');
+  if (!fs.existsSync(builtProvider)) return null;
+  try {
+    const mod = require(builtProvider);
+    if (typeof mod.performLocalRelease !== 'function') return null;
+    return mod;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the effective assignment-provider kind for this repo ('local-file' | 'github'),
+ * or null when it cannot be determined. Prefers reading context/settings/
+ * assignment-provider-settings.json directly (project settings first, matching
+ * effective-assignment-provider-settings.ts's own lookup precedence) rather than shelling
+ * out to or refactoring that CLI-shaped file (see plan Unresolved Question 1) — this task's
+ * scope is the Stop hook, not that file. Returns null (never guesses) when no settings file
+ * is present/parseable or names no provider kind for a project entry.
+ *
+ * Deliberately reads ONLY the project settings file (context/settings/
+ * assignment-provider-settings.json relative to repo root) — the common case for this repo
+ * and the one confirmed present. The effective() merge/repo-matching logic in
+ * effective-assignment-provider-settings.ts is intentionally NOT reimplemented here (that
+ * would fork a second merge algorithm); a repo whose provider kind can only be resolved via
+ * global settings or multi-project merge degrades to "unknown, skip assignment-layer
+ * release" rather than guessing.
+ */
+function resolveAssignmentProviderKind(root) {
+  const settingsFile = path.join(root, 'context', 'settings', 'assignment-provider-settings.json');
+  const settings = readJsonFile(settingsFile);
+  if (!settings) return null;
+  const candidates = [];
+  if (settings.defaults && settings.defaults.provider) candidates.push(settings.defaults.provider);
+  if (Array.isArray(settings.projects)) {
+    for (const project of settings.projects) {
+      if (project && project.provider) candidates.push(project.provider);
+    }
+  }
+  const kind = candidates.map(p => p && p.kind).find(k => k === 'local-file' || k === 'github');
+  return kind || null;
+}
+
+/**
+ * Refresh handoff.json by merge (read+spread the existing file's JSON, overwrite only the
+ * fields this task owns), mirroring advanceState's own handoff-write shape
+ * (`{ ...loadJson(...), ...sidecarBase(slug), summary, current_state_ref: "state.json",
+ * next_steps, blockers: [], warnings: [] }`) and current-pointer.js's writePerActorCurrent
+ * write idiom (`fs.writeFileSync(file, JSON.stringify(payload, null, 2) + "\n")`). next_steps
+ * is appended to (not clobbered) when a provider-release next-step is due.
+ */
+function refreshHandoffAfterRelease(artifactDir, slug, state, providerReleasePending, providerReleaseNextCommand) {
+  const file = path.join(artifactDir, 'handoff.json');
+  const existing = readJsonFile(file) || {};
+  const status = state ? normalizedStatus(state.status || 'unknown') : 'unknown';
+  const phase = state ? normalizedStatus(state.phase || 'unknown') : 'unknown';
+  const summary = (state && state.next_action && state.next_action.summary)
+    ? String(state.next_action.summary)
+    : `session ended at status:${status} phase:${phase}`;
+  const existingNextSteps = Array.isArray(existing.next_steps) ? existing.next_steps.slice() : [];
+  const nextSteps = existingNextSteps.slice();
+  if (providerReleasePending && providerReleaseNextCommand && !nextSteps.includes(providerReleaseNextCommand)) {
+    nextSteps.push(providerReleaseNextCommand);
+  }
+  const payload = {
+    ...existing,
+    schema_version: existing.schema_version || '1.0',
+    task_slug: existing.task_slug || slug,
+    summary,
+    current_state_ref: 'state.json',
+    next_steps: nextSteps,
+    ...(providerReleasePending ? { provider_release_pending: true } : {}),
+    ...(providerReleaseNextCommand ? { provider_release_next_command: providerReleaseNextCommand } : {}),
+  };
+  fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+/**
+ * #292 Wave 2: on a Stop event whose resolved session is at a NON-terminal status, release
+ * the session's liveness claim (always, provider-agnostic — AC1) and, for the local-file
+ * assignment provider, its durable assignment claim too (AC2), then refresh handoff.json
+ * (AC4). A terminal-status session (already released by advance-state) is a deliberate no-op
+ * (AC5). For the github provider, never calls render-release or gh — only records an
+ * honestly-labeled pending intent in handoff.json (AC3). Actor-scoped: only ever releases
+ * the CURRENT actor's own held claim (AC6, enforced inside performLocalRelease).
+ *
+ * Called once from run(), reusing analyze()'s already-resolved latestArtifactDir — this
+ * function does not re-derive "what is the active session" a second time.
+ *
+ * Fail-open (AC7): the entire body is wrapped in one try/catch. Any failure degrades to a
+ * single stderr diagnostic and returns, never throwing, never affecting the Stop hook's exit
+ * code or goal-fit's warnings/blocking contract (this function's return value is unused by
+ * that contract).
+ *
+ * @param {string} root - repo root (as resolved by findRepoRoot)
+ * @param {string|null} artifactDir - analyze()'s already-resolved latestArtifactDir
+ */
+function releaseOnNonTerminalStop(root, artifactDir) {
+  try {
+    if (!artifactDir) return; // no active session resolved — nothing to release.
+
+    const state = readJsonFile(path.join(artifactDir, 'state.json'));
+    if (!state) return; // AC5: no state.json — nothing to gate a release decision on.
+
+    const sidecar = loadWorkflowSidecarBuilt();
+    if (!sidecar) {
+      process.stderr.write('[Hook] Goal Fit: stop-hook release skipped — build/src/cli/workflow-sidecar.js not available (LIVENESS_TERMINAL boundary unknown).\n');
+      return;
+    }
+
+    const status = normalizedStatus(state.status || 'unknown');
+    if (sidecar.LIVENESS_TERMINAL.has(status)) return; // AC5: terminal — advance-state already released.
+
+    // Slug: artifact dir's basename, or state.json's own task_slug field — reuse whichever
+    // this file already has, never a new slug-derivation rule.
+    const slug = (state.task_slug && String(state.task_slug).trim()) || path.basename(artifactDir);
+
+    const { actor } = resolveActor(process.env);
+    if (isUnresolvedActor(actor)) {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook release skipped for "${safeOneLine(slug, 80)}" — actor identity is unresolved; never releasing under a synthetic identity.\n`);
+      return;
+    }
+
+    const flowAgentsDir = path.dirname(artifactDir);
+    const nowIso = new Date().toISOString();
+
+    // AC1: ALWAYS emit the liveness release, regardless of provider kind — liveness is
+    // provider-agnostic and this is the ONE shared writer every other liveness emitter uses.
+    try {
+      require('./lib/liveness-write.js').appendLivenessEvent(flowAgentsDir, {
+        type: 'release',
+        subjectId: slug,
+        actor,
+        at: nowIso,
+        source: 'stop-hook',
+      });
+    } catch (err) {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook liveness release failed for "${safeOneLine(slug, 80)}": ${safeOneLine(err && err.message || err, 160)}\n`);
+    }
+
+    // Resolve the effective assignment-provider kind — unknown means "do not guess",
+    // skip the assignment-layer release entirely (fail-open).
+    const providerKind = resolveAssignmentProviderKind(root);
+    if (!providerKind) {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook release — provider kind unknown for "${safeOneLine(slug, 80)}", skipping assignment-layer release (liveness release already emitted).\n`);
+      refreshHandoffAfterRelease(artifactDir, slug, state, false, null);
+      return;
+    }
+
+    let providerReleasePending = false;
+    let providerReleaseNextCommand = null;
+
+    if (providerKind === 'local-file') {
+      const provider = loadAssignmentProviderBuilt();
+      if (!provider) {
+        process.stderr.write('[Hook] Goal Fit: stop-hook local-file release skipped — build/src/cli/assignment-provider.js not available.\n');
+      } else {
+        try {
+          // Mirror assignment-provider.ts's loadActorStruct() exactly: runtime is derived via
+          // detectRuntime (not a literal 'unknown'), since serializeActor()'s comparison key
+          // includes runtime — a mismatched runtime segment here would make performLocalRelease's
+          // AC6 actor-match check wrongly treat this session's own claim as foreign.
+          //
+          // actorKey: opts.actorKey MUST be the same canonical `resolveActor(env).actor` string
+          // already resolved above (`actor`) — the identical bare-or-triple form
+          // computeEffectiveState()'s holderActorKey preference (`record.actor_key ||
+          // serializeActor(record.actor)`) and performLocalRelease's mirrored ownership check
+          // both key on. Without this, an explicit-override actor's release-side comparison
+          // would fall back to serializeActor(releasedBy) — a re-derived triple that never
+          // equals the stored bare actor_key — and this hook would wrongly treat its own claim
+          // as foreign (the #291 seam, relocated to the release path; see performLocalRelease's
+          // doc comment in src/cli/assignment-provider.ts).
+          const releasedBy = { runtime: detectRuntime(process.env), session_id: actor, host: os.hostname(), human: null };
+          const artifactRoot = flowAgentsArtifactRoot(root);
+          provider.performLocalRelease(artifactRoot, slug, releasedBy, {
+            reason: 'stop-hook non-terminal release',
+            tolerateNoActiveClaim: true,
+            actorKey: actor,
+          });
+        } catch (err) {
+          process.stderr.write(`[Hook] Goal Fit: stop-hook local-file release failed for "${safeOneLine(slug, 80)}": ${safeOneLine(err && err.message || err, 160)}\n`);
+        }
+      }
+    } else {
+      // AC3: github (or any non-local-file kind) — render-don't-execute. Never call
+      // render-release, never invoke gh. Disclose the pending intent honestly.
+      providerReleasePending = true;
+      providerReleaseNextCommand = `npm run workflow -- assignment-provider status --provider github --subject-id "${slug}" ...   # then: assignment-provider render-release --provider github --subject-id "${slug}" ... (emits the gh argv to run)`;
+    }
+
+    // AC4: refresh handoff.json — merge, never fully overwrite.
+    refreshHandoffAfterRelease(artifactDir, slug, state, providerReleasePending, providerReleaseNextCommand);
+  } catch (err) {
+    // Fail-open (AC7): any unexpected failure anywhere above (JSON parse error, fs error,
+    // etc.) must never crash the Stop hook or affect its exit code / goal-fit's output.
+    try {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook release logic error (fail-open): ${safeOneLine(err && err.message || err, 160)}\n`);
+    } catch { /* best-effort diagnostic only */ }
+  }
+}
+
 async function run(rawInput) {
   const input = parseJson(rawInput);
   const root = findRepoRoot(input.cwd || process.cwd());
   const mode = resolveGoalFitMode();
   if (mode === 'off') return rawInput;
   const result = await analyze(root);
+  // #292 Wave 2: additive side effect only — never changes analyze()'s warnings/blocking
+  // contract or this function's return value. Reuses analyze()'s already-resolved
+  // latestArtifactDir rather than re-deriving a second "what is the active session" path.
+  // Runs regardless of whether goal-fit itself has any warnings this turn (AC1: the
+  // liveness release must always be attempted on a non-terminal Stop, independent of
+  // whether goal-fit found anything to warn about).
+  releaseOnNonTerminalStop(root, result.latestArtifactDir || null);
   if (result.warnings.length === 0) {
     clearBlockStreak(root);
     return rawInput;
@@ -1937,4 +2194,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { analyze, run, resolveGoalFitMode, uncheckedInSection, findRepoRoot, sidecarGuidance, safeOneLine, captureCrossReference, bundleEnforcement, loadActiveFlowStep, readCommandLog, resolveTrustedCommand, declaredManifestTarget, verifyCommandLogChain, CHAIN_GENESIS_VERIFY, hasLaunderingOperator };
+module.exports = { analyze, run, resolveGoalFitMode, uncheckedInSection, findRepoRoot, sidecarGuidance, safeOneLine, captureCrossReference, bundleEnforcement, loadActiveFlowStep, readCommandLog, resolveTrustedCommand, declaredManifestTarget, verifyCommandLogChain, CHAIN_GENESIS_VERIFY, hasLaunderingOperator, releaseOnNonTerminalStop };

package/context/scripts/hooks/workflow-steering.js

@@ -19,6 +19,7 @@ const path = require('path');
 const { readLivenessEvents, freshHolders } = require('./lib/liveness-read');
 const { resolveActor } = require('./lib/actor-identity');
 const { flowAgentsArtifactRootsForRead } = require('./lib/local-artifact-paths');
+const { readCurrentPointer } = require('./lib/current-pointer');
 
 const STEERING = {
   'tool-planner': [
@@ -102,7 +103,48 @@ function readJson(file) {
   }
 }
 
+/**
+ * #291 (Conflict #2, Wave 2 Task 2.4): actor-scoped preference consulted BEFORE the global
+ * newest-mtime scan below. For each read-root, resolve the "current" pointer via
+ * `readCurrentPointer` (per-actor `current/<actor>.json` preferred, legacy global
+ * `current.json` fallback — the same single choke point every other Wave 2 consumer uses) and,
+ * if it names a session dir whose `state.json` is still in an ACTIVE_STATE_STATUSES status,
+ * return that state immediately — so actor A's own ambient steering hint always prefers A's own
+ * current task over a globally-newer-mtime `state.json` some other actor (B) happened to touch
+ * more recently. Returns null (never throws) when no root yields an actor-scoped resolution,
+ * so the caller falls through to the unchanged global scan below — this is the compat-shim
+ * guarantee: when `actorKey` is empty/unresolved and/or no per-actor file exists yet, this
+ * degrades to the SAME legacy-`current.json`-or-nothing lookup the compat shim already performs
+ * for every other Wave 2 reader, so a single-session/CI/legacy-only fixture cannot fail to
+ * resolve here in a way it wouldn't already have resolved via the global scan.
+ *
+ * @param {string} root
+ * @param {string} actorKey
+ * @returns {{file: string, payload: object, mtimeMs: number}|null}
+ */
+function actorScopedWorkflowState(root, actorKey) {
+  for (const flowAgentsDir of flowAgentsArtifactRootsForRead(root)) {
+    const { payload: current } = readCurrentPointer(flowAgentsDir, actorKey);
+    if (!current) continue;
+    const slug = current.artifact_dir || current.active_slug;
+    if (typeof slug !== 'string' || !slug.trim()) continue;
+    const safe = slug.replace(/\.\.+/g, '').replace(/^[/\\]+/, '');
+    const dir = path.join(flowAgentsDir, safe);
+    if (!dir.startsWith(flowAgentsDir + path.sep) || !fs.existsSync(dir)) continue;
+    const file = path.join(dir, 'state.json');
+    let stat;
+    try { stat = fs.statSync(file); } catch { continue; }
+    const payload = readJson(file);
+    if (!payload || !ACTIVE_STATE_STATUSES.has(payload.status)) continue;
+    return { file, payload, mtimeMs: stat.mtimeMs };
+  }
+  return null;
+}
+
 function latestWorkflowState(root) {
+  const preferred = actorScopedWorkflowState(root, resolveActor(process.env).actor);
+  if (preferred) return preferred;
+
   const states = flowAgentsArtifactRootsForRead(root)
     .flatMap(artifactRoot => walkStateFiles(artifactRoot))
     .map(file => {

package/docs/adr/0001-flow-agents-consumes-flow.md

@@ -2,6 +2,8 @@
 title: ADR 0001: Flow Agents Consumes Flow For Workflow Enforcement
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0001: Flow Agents Consumes Flow For Workflow Enforcement
 
 Date: 2026-05-24

package/docs/adr/0002-flow-kits-as-extension-unit.md

@@ -2,6 +2,8 @@
 title: ADR 0002: Flow Kits As The Extension Unit
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0002: Flow Kits As The Extension Unit
 
 Flow Agents will use **Flow Kit** as the product and implementation term for installable workflow bundles, replacing the older "pack" vocabulary. A Flow Kit may contain Flow Definitions, skills, adapters, provider contracts, docs, and evals; the Kit Catalog lists available kits and installable assets, but the workflow semantics live in kit-owned Flow Definition files. This avoids overloading packaging metadata with process semantics and gives custom workflow authoring a clearer product language.

package/docs/adr/0003-flow-agents-coordinates-kits-and-adapters.md

@@ -2,6 +2,8 @@
 title: ADR 0003: Flow Agents Coordinates Kits And Adapters
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0003: Flow Agents Coordinates Kits And Adapters
 
 Flow Agents will not own the builder, or knowledge workflows as core behavior. Those out-of-the-box behaviors will be extracted into normal Flow Kits that use the same manifest, Flow Definition, skill, doc, provider, and eval contracts as third-party kits. Flow Agents owns kit validation, installation, runtime adapter selection, provider wiring, status/control commands, and runtime-specific export; Runtime Adapters own target-specific integration for local agent runtimes and API/framework agents.

package/docs/adr/0004-gates-expect-surface-claims.md

@@ -2,6 +2,8 @@
 title: ADR 0004: Gates Expect Hachure Trust Bundles
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0004: Gates Expect Hachure Trust Bundles
 
 Flow-backed kits will model rich gate evidence as claim expectations using the Hachure trust.bundle format rather than provider-specific requirements. A gate expectation can require `kind: "trust.bundle"`, a domain claim type such as `builder.verify.tests`, accepted trust statuses such as `verified`, and whether the expectation blocks the transition; project or runtime config maps claim types to trusted Surface producers and authority traces. This lets the Builder Kit use repo governance, command checks, CI, human decisions, or future producers without naming a specific provider in the Flow Definition.

package/docs/adr/0005-kubernetes-inspired-resource-contracts.md

@@ -2,6 +2,8 @@
 title: ADR 0005: Kubernetes-Inspired Kontour Resource Contracts
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0005: Kubernetes-Inspired Kontour Resource Contracts
 
 Date: 2026-05-27

package/docs/adr/0006-typescript-first-source-policy.md

@@ -2,6 +2,8 @@
 title: ADR 0006: TypeScript-First Source Policy
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0006: TypeScript-First Source Policy
 
 Date: 2026-05-31

package/docs/adr/0007-flow-skill-kit-tool-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0007: Flow / Skill / Kit / Tool Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0007: Flow / Skill / Kit / Tool Boundary
 
 **Date:** 2026-06-15  

package/docs/adr/0007-skill-audit.md

@@ -2,6 +2,8 @@
 title: "Skill Audit 2026-06-15: Flow / Skill / Kit / Tool Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # Skill Audit: Flow / Skill / Kit / Tool Boundary
 
 **Date:** 2026-06-15  

package/docs/adr/0008-kit-operation-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0008: Kit Operation Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0008: Kit Operation Boundary
 
 **Date:** 2026-06-15  

package/docs/adr/0009-canonical-hook-core-kit-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0009: Canonical Hook Core/Kit Boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0009: Canonical Hook Core/Kit Boundary
 
 **Date:** 2026-06-23

package/docs/adr/0010-workflow-trust-state-as-hachure-bundle.md

@@ -2,6 +2,8 @@
 title: "ADR 0010: Workflow Trust State as a Hachure Trust Bundle"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0010: Workflow Trust State as a Hachure Trust Bundle
 
 **Date:** 2026-06-23

package/docs/adr/0011-mcp-posture.md

@@ -2,6 +2,8 @@
 title: "ADR 0011: MCP Posture — Enforcement Stays Hooks; Surface Owns MCP Projection; No Auto-Injected Config"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0011: MCP Posture
 
 **Date:** 2026-06-24

package/docs/adr/0012-agent-coordination-as-liveness-claims.md

@@ -2,6 +2,8 @@
 title: "ADR 0012: Agent Coordination as Hachure Liveness Claims"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0012: Agent Coordination as Hachure Liveness Claims
 
 **Date:** 2026-06-24

package/docs/adr/0013-context-lifecycle.md

@@ -2,6 +2,8 @@
 title: "ADR 0013: Context Lifecycle — Workflow-Boundary Compaction, Freshness-Gated Reuse, and the Learning Split"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0013: Context Lifecycle
 
 **Date:** 2026-06-25

package/docs/adr/0014-core-vs-domain-kit-boundary.md

@@ -2,6 +2,8 @@
 title: "ADR 0014: Flow Agents core vs domain kits — the generic/kit boundary"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0014: Flow Agents core vs domain kits
 
 **Date:** 2026-06-25

package/docs/adr/0015-flow-flow-agents-boundary-reconciliation.md

@@ -2,6 +2,8 @@
 title: "ADR 0015: Flow / Flow Agents Boundary Reconciliation"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0015: Flow / Flow Agents Boundary Reconciliation
 
 **Date:** 2026-06-25

package/docs/adr/0016-three-hard-boundary-model.md

@@ -2,6 +2,8 @@
 title: "ADR 0016: The Three-Hard-Boundary Model — a FlowDefinition-Driven, Kit-Agnostic Core"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0016: The Three-Hard-Boundary Model — a FlowDefinition-Driven, Kit-Agnostic Core
 
 **Date:** 2026-06-26

package/docs/adr/0017-anti-gaming-trust-security-model.md

@@ -2,6 +2,8 @@
 title: "ADR 0017: The Anti-Gaming Trust Security Model — Layered Defense + External CI Anchor"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0017: The Anti-Gaming Trust Security Model — Layered Defense + External CI Anchor
 
 Status: Accepted

package/docs/adr/0018-freeze-local-shell-heuristics.md

@@ -2,6 +2,8 @@
 title: "ADR 0018: Freeze the Local Shell-Parsing Heuristics; Route New Enforcement to the CI Anchor"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0018: Freeze the Local Shell-Parsing Heuristics; Route New Enforcement to the CI Anchor
 
 Status: Accepted

package/docs/adr/0019-kit-dependency-ownership.md

@@ -2,6 +2,8 @@
 title: "ADR 0019: Kit Dependency Ownership"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0019: Kit Dependency Ownership
 
 **Date:** 2026-07-01  

package/docs/adr/0020-trust-reconcile-manifest-and-claim-classification.md

@@ -2,6 +2,8 @@
 title: "ADR 0020: Trust-Reconcile Manifest, Claim Classification, and Waivers"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0020: Trust-Reconcile Manifest, Claim Classification, and Waivers
 
 Status: Accepted

package/docs/adr/0021-assignment-leases-and-stale-claim-takeover.md

@@ -2,6 +2,8 @@
 title: "ADR 0021: Assignment Leases and Stale-Claim Takeover"
 ---
 
+> **FROZEN — immutable history.** Superseding/current decisions live in [`docs/decisions/`](../decisions/index.md). Do not edit.
+
 # ADR 0021: Assignment Leases and Stale-Claim Takeover
 
 **Date:** 2026-07-02
@@ -98,7 +100,7 @@ Five touchpoints, one policy:
 |---|---|---|
 | `workflow-steering.js`, every turn | read | one-line liveness digest; "superseded" interrupt for the held subject |
 | `pull-work` | read + write | exclude held; claim (liveness + provider) on selection |
-| `ensure-session` / pickup | read + write | refuse entry to a session dir under a fresh other-actor claim; supersede-then-enter if stale |
+| `ensure-session` / pickup | read + write | refuse entry to a session dir under a fresh other-actor claim; supersede-then-enter if stale (**implemented by #291**) |
 | `advance-state` + tool activity | write | heartbeat rides existing writes; no bespoke timer |
 | **publish (push / PR / merge)** | **read, blocking** | **verify-hold**: hard-stop if not the fresh, non-superseded holder |