@kontourai/flow-agents 2.3.0 → 2.4.0

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

@@ -3,7 +3,11 @@
  * Workflow Steering Hook
  *
  * Injects phase-transition reminders after use_subagent calls complete and
- * ambient workflow-state reminders at the start of the next user turn.
+ * re-grounds the active workflow state at the start of every user turn and on
+ * SessionStart. SessionStart fires after context compaction and on resume, so
+ * re-injecting the goal/phase/next-step there is what makes an in-flight goal
+ * survive context loss instead of relying on the model voluntarily re-reading
+ * the sidecar.
  *
  * Non-blocking — always exits 0.
  */
@@ -12,6 +16,9 @@
 
 const fs = require('fs');
 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 STEERING = {
   'tool-planner': [
@@ -96,7 +103,8 @@ function readJson(file) {
 }
 
 function latestWorkflowState(root) {
-  const states = walkStateFiles(path.join(root, '.flow-agents'))
+  const states = flowAgentsArtifactRootsForRead(root)
+    .flatMap(artifactRoot => walkStateFiles(artifactRoot))
     .map(file => {
       let stat;
       try { stat = fs.statSync(file); } catch { return null; }
@@ -198,6 +206,169 @@ function contextMapSteering(root) {
   ].join(' ');
 }
 
+function promptText(input) {
+  const candidates = [
+    input && input.prompt,
+    input && input.user_prompt,
+    input && input.message,
+    input && input.text,
+    input && input.tool_input && input.tool_input.prompt,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim()) return candidate;
+  }
+  return '';
+}
+
+function looksLikeBuilderWork(text) {
+  const normalized = safeStateText(text, 2000).toLowerCase();
+  if (!normalized) return false;
+  const readOnlyIntent = /\b(read[- ]only|review[- ]only|no (source |code |file )?(changes?|edits?|modifications?)|do not (modify|edit|change|write|fix|implement|touch)|don't (modify|edit|change|write|fix|implement|touch)|dont (modify|edit|change|write|fix|implement|touch))\b/.test(normalized);
+  if (readOnlyIntent) return false;
+  const questionOnlyIntent = /^(what|which|who|when|where|why|how)\b/.test(normalized);
+  if (questionOnlyIntent) return false;
+  const noCodeQuestion = /\b(explain|describe|summari[sz]e|what is|how does|how do i|why does|review|critique)\b/.test(normalized)
+    && !/\b(build|create|implement|ship|deliver|fix|debug|refactor|add|update|change|modify|wire|migrate|install|scaffold|write|code)\b/.test(normalized);
+  if (noCodeQuestion) return false;
+  const verificationOnlyIntent = /\b(validate|test|verify|check)\b/.test(normalized)
+    && !/\b(build|create|implement|ship|deliver|fix|debug|refactor|add|update|change|modify|wire|migrate|install|scaffold|write|code)\b/.test(normalized);
+  if (verificationOnlyIntent) return false;
+  const hasWorkVerb = /\b(build|create|implement|ship|deliver|fix|debug|refactor|add|update|change|modify|wire|migrate|install|scaffold|write|code)\b/.test(normalized);
+  const hasWorkObject = /\b(api|endpoint|component|feature|bug|failing test|regression|integration|hook|script|cli|config|schema|migration)\b/.test(normalized);
+  const hasRequestLanguage = /\b(can you|please|let's|lets|need|should|make|ensure|support|add|update|fix|work on)\b/.test(normalized);
+  return hasWorkVerb || (hasWorkObject && hasRequestLanguage);
+}
+
+function builderWorkflowSteering(input) {
+  if (!looksLikeBuilderWork(promptText(input))) return '';
+  return [
+    'BUILDER WORKFLOW ROUTE: this user prompt looks like coding/build work.',
+    'Builder lifecycle: shape raw ideas -> build selected work -> publish verified branch/PR -> learn correction feedback.',
+    'Before source edits or implementation commands, activate Builder Kit delivery workflow.',
+    'If the user explicitly requested TDD, activate `tdd-workflow`; otherwise activate `deliver` and keep the session on `builder.build`.',
+    'Use `npm run workflow:sidecar -- ensure-session --flow-id builder.build ...` when the repo provides the sidecar writer.',
+    'After local verification, continue to publish/release-readiness and learning-review; do not treat local verification as terminal delivery.',
+    'Do not bypass plan-work -> execute-plan -> review-work -> verify-work for coding tasks; direct implementation is only acceptable when the user explicitly asks for no workflow or explanation-only help.',
+  ].join(' ');
+}
+
+/**
+ * Compose the RESUME block for SessionStart.
+ *
+ * Reads trust.bundle, handoff.json, and the liveness stream beside state.json;
+ * all reads are fail-open (errors → skip that section, never throw).
+ *
+ * Returns a multi-line string starting with "RESUME: <slug> status:<s> phase:<p>"
+ * or '' if the current state has status 'done', 'archived', or 'accepted'.
+ *
+ * @param {string} root     Repository root
+ * @param {{ file: string, payload: object }} current  Latest active state entry
+ * @returns {string}
+ */
+function resumeSteering(root, current) {
+  try {
+    const state = current.payload;
+    const workflowDir = path.dirname(current.file);
+    const slug = state.task_slug || path.basename(workflowDir);
+    const next = state.next_action || {};
+
+    if (next.status === 'done' || state.status === 'archived' || state.status === 'accepted') return '';
+
+    const lines = [];
+
+    // Header line
+    lines.push(`RESUME: ${slug} status:${safeStateText(state.status, 60)} phase:${safeStateText(state.phase, 60)}`);
+
+    // Full next action (240-char display path, not the 80-char normalization)
+    const nextSummary = next.summary ? safeStateText(next.summary, 240) : 'none';
+    lines.push(`Next action: ${nextSummary}`);
+
+    // Plan artifact path
+    let planPath = 'not found';
+    try {
+      const artifactPaths = Array.isArray(state.artifact_paths) ? state.artifact_paths : [];
+      const planEntry = artifactPaths.find(p => typeof p === 'string' && p.endsWith('--plan-work.md'));
+      if (planEntry) {
+        planPath = planEntry;
+      } else {
+        const candidate = path.join(workflowDir, `${slug}--plan-work.md`);
+        if (fs.existsSync(candidate)) planPath = candidate;
+      }
+    } catch { /* skip */ }
+    lines.push(`Plan: ${planPath}`);
+
+    // Handoff: next_steps[0] and blockers
+    let nextStep = 'none';
+    let blockers = 'none';
+    try {
+      const handoff = readJson(path.join(workflowDir, 'handoff.json'));
+      if (handoff) {
+        const steps = Array.isArray(handoff.next_steps) ? handoff.next_steps : [];
+        if (steps.length > 0) nextStep = safeStateText(String(steps[0]), 240);
+        const bArr = Array.isArray(handoff.blockers) ? handoff.blockers : [];
+        if (bArr.length > 0) blockers = bArr.map(b => safeStateText(String(b), 120)).join(', ');
+      }
+    } catch { /* skip */ }
+    lines.push(`Next step: ${nextStep}`);
+    lines.push(`Blockers: ${blockers}`);
+
+    // Trust bundle
+    try {
+      const bundle = readJson(path.join(workflowDir, 'trust.bundle'));
+      if (bundle) {
+        const claims = Array.isArray(bundle.claims) ? bundle.claims : [];
+        let verified = 0;
+        let disputed = 0;
+        const unresolved = [];
+        for (const claim of claims) {
+          if (!claim || typeof claim !== 'object') continue;
+          const status = String(claim.status || '');
+          if (status === 'verified') {
+            verified++;
+          } else if (status === 'disputed' || status === 'unknown') {
+            disputed++;
+            unresolved.push(claim);
+          }
+        }
+        const total = claims.length;
+        lines.push(`Trust: ${verified} verified / ${disputed} disputed / ${total} total`);
+        for (const claim of unresolved) {
+          const id = safeStateText(String(claim.id || ''), 120);
+          const st = safeStateText(String(claim.status || ''), 30);
+          lines.push(`  - ${id} (${st}) → npm run workflow:sidecar -- claim ${id} ${workflowDir}`);
+        }
+      } else {
+        lines.push('Trust: no trust data available');
+      }
+    } catch { /* skip */ }
+
+    // Liveness advisory
+    try {
+      const resolved = resolveActor(process.env);
+      const selfActor = resolved.actor || 'local';
+      const events = flowAgentsArtifactRootsForRead(root)
+        .flatMap(artifactRoot => readLivenessEvents(path.join(artifactRoot, 'liveness', 'events.jsonl')));
+      if (events.length > 0) {
+        // selfActor (for exclusion matching) stays raw here; only the display strings pushed
+        // into `lines` are sanitized below, since holders come from the shared multi-writer
+        // liveness stream and must be treated as untrusted display input (#287 fix iteration 1).
+        const holders = freshHolders(events, slug, selfActor, Date.now());
+        for (const h of holders) {
+          lines.push(`[LIVENESS WARNING: another agent appears live on this work: actor ${safeStateText(h.actor)}, last seen ${h.lastAt}]`);
+        }
+      }
+      lines.push(`ACTOR: ${safeStateText(selfActor)} (${resolved.source})`);
+    } catch { /* skip */ }
+
+    // Pull-work route hint
+    lines.push('To continue: resume this work. Or run pull-work to assess WIP and start new/parallel work.');
+
+    return lines.join('\n');
+  } catch {
+    return '';
+  }
+}
+
 function run(rawInput) {
   try {
     const input = JSON.parse(rawInput);
@@ -217,9 +388,31 @@ function run(rawInput) {
       shouldAppendWorkflowContext = hints.length > 0;
     }
 
-    if (event === 'UserPromptSubmit' && current && stateNeedsAmbientSteering(current.payload)) {
-      hints.push('WORKFLOW STATE ATTENTION: current sidecars show unresolved workflow state at turn start.');
-      shouldAppendWorkflowContext = true;
+    if ((event === 'UserPromptSubmit' || event === 'SessionStart') && current) {
+      const stateHint = stateSteering(root);
+      if (stateHint) {
+        hints.push(stateNeedsAmbientSteering(current.payload)
+          ? 'WORKFLOW STATE ATTENTION: current sidecars show unresolved workflow state at turn start.'
+          : 'WORKFLOW STATE: an active task is in progress — re-ground the recorded goal and resume the next step before doing anything else.');
+        hints.push(stateHint);
+        const contextHint = contextMapSteering(root);
+        if (contextHint) hints.push(contextHint);
+      }
+    }
+
+    if (event === 'UserPromptSubmit') {
+      const builderHint = builderWorkflowSteering(input);
+      if (builderHint) {
+        hints.push(builderHint);
+        const contextHint = contextMapSteering(root);
+        if (contextHint) hints.push(contextHint);
+      }
+    }
+
+    // SessionStart only: append the RESUME block for richer situational awareness
+    if (event === 'SessionStart' && current) {
+      const resumeBlock = resumeSteering(root, current);
+      if (resumeBlock) hints.push(resumeBlock);
     }
 
     if (shouldAppendWorkflowContext) {
@@ -247,4 +440,17 @@ if (require.main === module) {
   });
 }
 
-module.exports = { run, stateSteering, critiqueSteering, contextMapSteering, latestWorkflowState, findRepoRoot, safeStateText, stateNeedsAmbientSteering };
+module.exports = {
+  run,
+  stateSteering,
+  critiqueSteering,
+  contextMapSteering,
+  latestWorkflowState,
+  findRepoRoot,
+  safeStateText,
+  stateNeedsAmbientSteering,
+  resumeSteering,
+  promptText,
+  looksLikeBuilderWork,
+  builderWorkflowSteering,
+};

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

@@ -7,6 +7,8 @@ title: "ADR 0007: Flow / Skill / Kit / Tool Boundary"
 **Date:** 2026-06-15  
 **Status:** Accepted
 
+> **Cross-Kit Skill Sharing resolved by [ADR 0019](./0019-kit-dependency-ownership.md) (2026-07-01).** The "Cross-Kit Skill Sharing: DEFERRED" question below is resolved: the npm-dependency-style model (Kit B declares a peer dependency on Kit A and consumes its skills by reference) is adopted at the Flow Agents extension layer via a `kit.json` `dependencies` field. The single-kit-ownership principle recorded here still stands; only the deferral is lifted.
+
 ---
 
 ## Context

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

@@ -97,6 +97,41 @@ The broader boundary reconciliation (issue #174) is phased:
 
 **Invariant that must survive migration (#183 Finding 2):** `WorkflowRun.status.conditions` are writable summaries; the gate re-derives from Hachure claims via Surface; `conditions[].evidenceRefs` cite claim IDs. **Do not fuse Resource and claim** — the separation (a friendly mutable surface over an un-gameable derived core) is the architecture.
 
+### Status update (2026-07-01) — Tier 2 Phase 3 landed and hardened
+
+**Phase 3 ("hooks") of the Tier 2 migration has landed — this is not an unfinished step.**
+PRs #204–#209 (P-a through P-d, ADR 0016 Abstraction A) implemented the FlowDefinition →
+enforcement bridge: P-a, a shared `src/lib/flow-resolver.ts` resolver
+(`resolveActiveFlowStep`) that turns `(active_flow_id, active_step_id)` into a gate's
+`expects[]`; P-b, declared-claim producers (`record-gate-claim` stamps kit-namespaced
+claims per the active FlowDefinition's gate); P-c, gate enforcement in
+`scripts/hooks/stop-goal-fit.js` reading `activeFlowStep.gateExpects[]` to select claims by
+declared `claimType`; and P-d, `phase_map`-driven `advance-state --flow-definition` plus
+retirement of the `-legacy` dual-emit shadow, so a live FlowDefinition-driven session emits
+only kit-namespaced claims.
+
+**It was then red-teamed in PR #215, which found the literal end-state unsafe.** The literal
+Abstraction A text — declared-only enforcement, no `workflow.*` fallback — composed into a
+HIGH-severity (OWASP A01/A04) gate-bypass chain: a forged `current.json` pointing at an
+agent-authored `.flow.json` with an empty `expects: []` made the pure if/else selection logic
+return `false` for every claim, silently skipping all re-derivation, tamper-detection, and
+high/critical enforcement. PR #215 closed this by replacing the if/else with a **permanent
+union-enforcement floor** — `workflow.*` claims are *always* enforced alongside whatever a
+declared FlowDefinition adds, never instead of it — plus an empty-`expects[]`
+`gate misconfiguration:` `HARD_BLOCK`. **This union floor and HARD_BLOCK are an intentional,
+tested departure from Abstraction A's literal "instead of" wording, not an unfinished step
+toward it, and must not be "completed" by removing them** (see ADR 0016 and ADR 0018, which
+independently forbids adding new local `config-protection.js` patterns for this class of
+vector and routes new self-tamper/kill-switch findings to Layer 4 instead).
+
+**The one gap this left named and open — kit FlowDefinition files
+(`kits/*/flows/*.flow.json`) had no CODEOWNERS coverage, so a narrowed-but-nonempty
+`expects[]` edit had no owner-review trip-wire — is closed as of 2026-07-01, per ADR 0018
+Decision #2** (a self-tamper/kill-switch vector routes to Layer 4 — CODEOWNERS + a required
+regression test — not a new `config-protection.js` matcher). This closes the last open item
+from this Reassessment's Phase 3; Phases 4–6 (resume/evals, retire sidecars, Flow kernel)
+remain scoped as described above.
+
 ## Consequences
 
 - **No bespoke trust-bundle schema validator in flow-agents.** Surface is the canonical

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

@@ -0,0 +1,62 @@
+---
+title: "ADR 0019: Kit Dependency Ownership"
+---
+
+# ADR 0019: Kit Dependency Ownership
+
+**Date:** 2026-07-01  
+**Status:** Accepted
+
+---
+
+## Context
+
+ADR 0007 ("Flow / Skill / Kit / Tool Boundary") left one question explicitly open under **Cross-Kit Skill Sharing: DEFERRED**: can a skill be shared across kits, and if so, how is that dependency declared and enforced? The motivating case is concrete and already live in this repository — the Builder Kit's `learning-review` skill invokes the Knowledge Kit's `knowledge-capture` skill (`kits/knowledge/skills/knowledge-capture/SKILL.md`) for durable knowledge storage. Today that cross-kit call is undeclared: nothing validates that Knowledge is present when Builder is installed or activated, so the dependency fails silently at agent-invocation time rather than loudly at install/activate time.
+
+ADR 0007 named the leading candidate: *"an npm-dependency model: Kit B declares a peer dependency on Kit A and invokes Kit A's skills as a consumer, without absorbing them into Kit B's skill list."* It deferred adoption "until a concrete cross-kit case requires it." That case is now required, so this ADR resolves the deferral.
+
+The open design question is **ownership**: does a cross-kit `dependencies` field belong in the Flow-owned container schema (`@kontourai/flow`'s `flow-kit-container.schema.json`), or in the Flow Agents extension layer?
+
+---
+
+## Decision
+
+**Kit `dependencies` lives entirely in the Flow Agents extension layer. No `@kontourai/flow` schema or code change is required or planned.**
+
+The `dependencies` field is a `kit.json` array of `{ kit_id, reason? }` entries validated and enforced exclusively by Flow Agents code:
+
+- **Shape** (`src/flow-kit/validate.ts` `parseKitDependencies`, wired into `validateKitRepository`): each entry must be an object with a kebab-case `kit_id` (`^[a-z][a-z0-9-]*$`), no self-reference, and no duplicate `kit_id`. `reason` is an optional string. Shape errors are hard errors at `flow-agents kit install` / `inspect` / `validate` time.
+- **Install-time presence** (`src/cli/kit.ts`): a non-blocking warning is printed when a declared dependency is absent from the destination's **local** registry. This check is deliberately scoped to the local registry only (not the built-in catalog) — an accepted v1 limitation, documented, not hidden.
+- **Activation-time presence** (`src/runtime-adapters.ts`): a **hard error** (non-zero exit) when a declared `kit_id` is absent from the union of built-in catalog kits and locally-installed kits at activation time.
+
+### Grounding: why the extension layer, not Flow
+
+Three independent lines of evidence put `dependencies` on the Flow Agents side of the boundary:
+
+1. **The container schema already permits it, agent-blind.** `@kontourai/flow`'s `flow-kit-container.schema.json` declares `"additionalProperties": true` and states that *"Consumer products (such as Flow Agents) may define additional asset-class fields as extensions; unknown top-level fields are consumer extensions and core validation ignores-but-permits them."* A `dependencies` array is schema-legal in Flow today with zero Flow-side change. Flow's `validateKitContainer` only enforces `schema_version` / `id` / `name` / `flows`; it never touches unknown top-level fields.
+
+2. **ADR 0008's Dividing Test lands it on Flow Agents.** ADR 0008 asks: *"Does the operation need to INTERPRET the agent extension (what a skill or adapter MEANS), or only the container ... Container-only → Flow. Extension-interpreting → Flow Agents."* A kit-to-kit dependency exists **only** because one kit's *skill* invokes another kit's *skill* — that is interpreting what a skill means, squarely on the Flow Agents side of the line. Flow's gate / FlowDefinition engine has no concept of "kit A needs kit B" and needs none to evaluate gates.
+
+3. **There is an existing precedent for exactly this pattern.** `src/flow-kit/validate.ts` already derives K0/K1/K2 conformance and consumer targets purely from Flow Agents-owned code reading the same `kit.json` that Flow validates agent-blind. `dependencies` follows the identical pattern: a new Flow Agents-recognized (not Flow-recognized) metadata field, added to a `KNOWN_METADATA_FIELDS` allowlist so it is never misreported as an unknown third-party extension namespace.
+
+### First declared dependency
+
+`kits/builder/kit.json` declares `dependencies: [{ "kit_id": "knowledge", "reason": "learning-review invokes knowledge-capture ... for durable knowledge storage" }]`, making the previously-implicit Builder→Knowledge relationship explicit and enforceable.
+
+---
+
+## Consequences
+
+- **Single-repo change.** Because no cross-repo change is needed, there is no cross-repo prerequisite: everything lands in one `flow-agents` change. The Flow container contract is untouched.
+- **Install stays non-blocking; activation is the hard gate.** Keeping install-time checks advisory avoids breaking a consumer repo that has forked/customized `kits/catalog.json`; activation-time enforcement is where a genuinely-missing dependency fails loudly. This split is itself documented in `docs/kit-authoring-guide.md`.
+- **`dependencies` is metadata, not a K-level input.** It is presence/metadata, not evaluable-gate content, so it does NOT participate in K0/K1/K2 conformance scoring.
+- **Not a package manager.** `dependencies` declares and validates presence; it does not fetch, resolve version ranges, or order installs. Version-range resolution and transitive-dependency graphs remain out of scope (a possible future extension, still extension-layer-owned by this decision).
+
+---
+
+## References
+
+- [ADR 0007: Flow / Skill / Kit / Tool Boundary](./0007-flow-skill-kit-tool-boundary.md) — resolves its "Cross-Kit Skill Sharing: DEFERRED" question by adopting the npm-dependency-style model at the Flow Agents extension layer.
+- [ADR 0008: Kit Operation Boundary](./0008-kit-operation-boundary.md) — the "Dividing Test" that locates extension-interpreting operations in Flow Agents.
+- `@kontourai/flow`'s `flow-kit-container.schema.json` (`additionalProperties: true`, "ignores-but-permits" consumer extensions) and `validateKitContainer`.
+- `src/flow-kit/validate.ts` (`parseKitDependencies`, `KNOWN_METADATA_FIELDS`, `deriveKitTargets`), `src/cli/kit.ts` (install-time warning), `src/runtime-adapters.ts` (activation-time enforcement).