@kontourai/flow-agents 0.2.0 → 0.4.0

package/kits/knowledge/flows/compile.flow.json

@@ -0,0 +1,60 @@
+{
+  "id": "knowledge.compile",
+  "version": "1.0",
+  "steps": [
+    { "id": "select-raws", "next": "compile" },
+    { "id": "compile", "next": "link" },
+    { "id": "link", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "select-raws-gate": {
+      "step": "select-raws",
+      "expects": [
+        {
+          "id": "raw-ids-selected",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "One or more raw record IDs have been selected for compilation. Each ID must resolve to an existing raw record in the store.",
+          "claim": {
+            "type": "knowledge.compile.selection",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "compile-gate": {
+      "step": "compile",
+      "expects": [
+        {
+          "id": "compiled-record-provenance",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The compiled record has been created with provenance.source_ids listing every consumed raw ID, and source links (kind='source') from the compiled record to each raw record — satisfying the store contract's compiled record requirements.",
+          "claim": {
+            "type": "knowledge.compile.provenance",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "link-gate": {
+      "step": "link",
+      "expects": [
+        {
+          "id": "provenance-refs-resolve",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Every provenance ref in the compiled record resolves to a retrievable raw record via the store's get() operation. The graph index reflects all source links.",
+          "claim": {
+            "type": "knowledge.compile.link-integrity",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/flows/consolidate.flow.json

@@ -0,0 +1,77 @@
+{
+  "id": "knowledge.consolidate",
+  "version": "1.0",
+  "steps": [
+    { "id": "related-event", "next": "propose" },
+    { "id": "propose", "next": "evidence-gate" },
+    { "id": "evidence-gate", "next": "apply-or-reject" },
+    { "id": "apply-or-reject", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "related-event-gate": {
+      "step": "related-event",
+      "expects": [
+        {
+          "id": "related-compiled-records-found",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "One or more compiled records linked to the snapshot's topic have been identified. The trigger fires when new compiled records matching the snapshot topic (by category or explicit topic tag) are present. The result is a cluster of compiled record IDs that form the consolidation input.",
+          "claim": {
+            "type": "knowledge.consolidate.trigger",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "propose-gate": {
+      "step": "propose",
+      "expects": [
+        {
+          "id": "consolidation-proposal-recorded",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A consolidation proposal has been recorded. The proposal carries: the updated snapshot body (latest decisions), source_ids referencing every compiled record that contributed, and supersedes_ids referencing any prior snapshot(s) for the same topic. The snapshot record is NOT mutated at this step — only a consolidation proposal record and proposes link are created.",
+          "claim": {
+            "type": "knowledge.consolidate.proposal",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "evidence-gate": {
+      "step": "evidence-gate",
+      "expects": [
+        {
+          "id": "proposal-carries-source-refs",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The consolidation proposal evidence includes source_ids referencing every compiled record that contributed to the proposed snapshot body. Gate rejects if source_ids is empty or any referenced record does not exist. Also verifies that the proposer record has a 'proposes' link to the snapshot target.",
+          "claim": {
+            "type": "knowledge.consolidate.evidence",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "apply-gate": {
+      "step": "apply-or-reject",
+      "expects": [
+        {
+          "id": "consolidation-gate-decision",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A gate decision (apply or reject) has been recorded. If applied: snapshot body is updated via the store update op with the proposed body; supersede op links the new snapshot to any prior snapshots for the same topic; all superseded snapshots remain queryable with provenance intact. If rejected: the snapshot body is byte-identical to its pre-proposal state.",
+          "claim": {
+            "type": "knowledge.consolidate.gate-decision",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/flows/ingest.flow.json

@@ -0,0 +1,60 @@
+{
+  "id": "knowledge.ingest",
+  "version": "1.0",
+  "steps": [
+    { "id": "capture", "next": "classify" },
+    { "id": "classify", "next": "route" },
+    { "id": "route", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "capture-gate": {
+      "step": "capture",
+      "expects": [
+        {
+          "id": "raw-text-received",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Raw text and metadata have been received and are non-empty.",
+          "claim": {
+            "type": "knowledge.ingest.capture",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "classify-gate": {
+      "step": "classify",
+      "expects": [
+        {
+          "id": "classification-recorded",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The raw record has been classified and stored with a non-empty category and type='raw', satisfying the store contract's create op provenance requirements.",
+          "claim": {
+            "type": "knowledge.ingest.classification",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "route-gate": {
+      "step": "route",
+      "expects": [
+        {
+          "id": "routing-decision",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A routing decision has been recorded for the classified raw record (e.g. queue for compile, discard, or hold).",
+          "claim": {
+            "type": "knowledge.ingest.routing",
+            "subject": "decision",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/flows/retire.flow.json

@@ -0,0 +1,77 @@
+{
+  "id": "knowledge.retire",
+  "version": "1.0",
+  "steps": [
+    { "id": "identify", "next": "propose-retirement" },
+    { "id": "propose-retirement", "next": "evidence-gate" },
+    { "id": "evidence-gate", "next": "apply-or-reject" },
+    { "id": "apply-or-reject", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "identify-gate": {
+      "step": "identify",
+      "expects": [
+        {
+          "id": "target-record-found",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The record to be retired has been identified and is in a retirable status (active or implemented). The record ID and current status are surfaced for the proposal step.",
+          "claim": {
+            "type": "knowledge.retire.identify",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "propose-retirement-gate": {
+      "step": "propose-retirement",
+      "expects": [
+        {
+          "id": "retirement-proposal-recorded",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A retirement proposal has been recorded. The proposal carries: the target status (implemented or retired), the retirement rationale, and — when targetStatus is 'implemented' — an implementedByRef pointing to the implementing artifact (commit SHA, PR URL, issue number, etc.). The record is NOT mutated at this step — only a retirement proposal record and proposes link are created.",
+          "claim": {
+            "type": "knowledge.retire.proposal",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "evidence-gate": {
+      "step": "evidence-gate",
+      "expects": [
+        {
+          "id": "retirement-evidence-valid",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The retirement proposal evidence is valid: rationale is non-empty; implementedByRef is non-empty when targetStatus is 'implemented'; the target record exists and is in a state that allows the requested transition (active→implemented, active→retired, implemented→retired). Gate rejects if any required evidence field is missing or the transition is invalid.",
+          "claim": {
+            "type": "knowledge.retire.evidence",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "apply-gate": {
+      "step": "apply-or-reject",
+      "expects": [
+        {
+          "id": "retirement-gate-decision",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A gate decision (apply or reject) has been recorded. If applied: the record status is updated to the target status via the store retire op; the retirement evidence (rationale, implementedByRef, supersededByRef) is appended to the mutation log; the record body, links, and provenance remain intact; the record is excluded from default working-set queries (listByType, listByCategory, similarity detection). If rejected: the record status is byte-identical to its pre-proposal state.",
+          "claim": {
+            "type": "knowledge.retire.gate-decision",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/flows/store-contract.flow.json

@@ -0,0 +1,48 @@
+{
+  "id": "knowledge.store-contract",
+  "version": "1.0",
+  "steps": [
+    { "id": "verify-contract", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "verify-contract-gate": {
+      "step": "verify-contract",
+      "expects": [
+        {
+          "id": "contract-suite-passed",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The contract test suite has passed 100% against the target adapter, verifying round-trip integrity, required-evidence enforcement, and graph-index consistency.",
+          "claim": {
+            "type": "knowledge.store-contract.suite-result",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "mutation-provenance-enforced",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Every mutation operation (create, update, link, propose, apply, reject) rejects requests missing required provenance fields, as verified by the contract suite.",
+          "claim": {
+            "type": "knowledge.store-contract.provenance-enforcement",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "round-trip-integrity",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Records round-trip raw to stored to queried with category and links intact, as verified by the contract suite.",
+          "claim": {
+            "type": "knowledge.store-contract.round-trip",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/flows/synthesize.flow.json

@@ -0,0 +1,77 @@
+{
+  "id": "knowledge.synthesize",
+  "version": "1.0",
+  "steps": [
+    { "id": "detect-cluster", "next": "propose" },
+    { "id": "propose", "next": "evidence-gate" },
+    { "id": "evidence-gate", "next": "apply-or-reject" },
+    { "id": "apply-or-reject", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "detect-cluster-gate": {
+      "step": "detect-cluster",
+      "expects": [
+        {
+          "id": "similar-sources-found",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "At least one compiled record similar to the target concept has been identified via the similarity detector. Similarity v1 uses category match + link-overlap heuristic. The result is a cluster of source record IDs to synthesize from.",
+          "claim": {
+            "type": "knowledge.synthesize.cluster",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "propose-gate": {
+      "step": "propose",
+      "expects": [
+        {
+          "id": "proposal-recorded",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A proposal carrying source refs (proposer_id + source_ids in evidence) has been recorded via the store propose op. The concept body is NOT modified at this step — only a proposes link and mutation log entry are created.",
+          "claim": {
+            "type": "knowledge.synthesize.proposal",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "evidence-gate": {
+      "step": "evidence-gate",
+      "expects": [
+        {
+          "id": "proposal-carries-source-refs",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The proposal evidence includes source_ids referencing every compiled record that contributed to the proposed summary. Gate rejects if source_ids is empty or any referenced record does not exist.",
+          "claim": {
+            "type": "knowledge.synthesize.evidence",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "apply-gate": {
+      "step": "apply-or-reject",
+      "expects": [
+        {
+          "id": "mutation-gate-decision",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A gate decision (apply or reject) has been recorded. If applied: concept body is updated via the store apply op with rationale and all contributing source_ids in provenance. If rejected: the store reject op is called, the concept body is byte-identical to its pre-proposal state, and only a rejection log entry is appended.",
+          "claim": {
+            "type": "knowledge.synthesize.gate-decision",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/kit.json

@@ -0,0 +1,98 @@
+{
+  "schema_version": "1.0",
+  "id": "knowledge",
+  "name": "Knowledge Kit",
+  "product_name": "Knowledge Kit",
+  "description": "A Flow Kit for durable, gated knowledge storage. Provides a store contract with defined record types, mutation operations, and provenance rules \u2014 plus a default adapter backed by markdown files, YAML frontmatter, wikilinks, and a graph index.",
+  "flows": [
+    {
+      "id": "knowledge.store-contract",
+      "path": "flows/store-contract.flow.json",
+      "description": "Gate that requires contract-suite evidence before a store implementation is accepted."
+    },
+    {
+      "id": "knowledge.ingest",
+      "path": "flows/ingest.flow.json",
+      "description": "Ingest raw captures: capture \u2192 classify \u2192 route. Gate on classify requires category + type='raw' classification evidence per the store contract create op."
+    },
+    {
+      "id": "knowledge.compile",
+      "path": "flows/compile.flow.json",
+      "description": "Compile classified raws into durable notes: select-raws \u2192 compile \u2192 link. Gate on compile requires provenance refs to every consumed raw record."
+    },
+    {
+      "id": "knowledge.synthesize",
+      "path": "flows/synthesize.flow.json",
+      "description": "Synthesize compiled sources into concept summaries: detect-cluster \u2192 propose \u2192 evidence-gate \u2192 apply-or-reject. Mutation-gate policy: no summary mutates without an approved proposal carrying source refs; rejection leaves store untouched."
+    },
+    {
+      "id": "knowledge.consolidate",
+      "path": "flows/consolidate.flow.json",
+      "description": "Consolidate related compiled records into a living decision snapshot: related-event trigger -> consolidation proposal -> evidence gate -> apply-or-reject. Creates or updates a snapshot record; supersedes prior snapshots via supersede op (never deletes). Reuses S3 mutation-gate machinery."
+    },
+    {
+      "id": "knowledge.retire",
+      "path": "flows/retire.flow.json",
+      "description": "Retire implemented or obsolete records from the working set via gated lifecycle: identify \u2192 propose-retirement \u2192 evidence-gate \u2192 apply-or-reject. Evidence required: retirement rationale + implementedByRef (when targeting 'implemented' status) or supersededByRef (optional, for 'retired'). Rejection leaves record status byte-identical. Retired records remain fully queryable with provenance via includeRetired flag."
+    }
+  ],
+  "docs": [
+    {
+      "id": "knowledge.readme",
+      "path": "docs/README.md"
+    },
+    {
+      "id": "knowledge.store-contract-doc",
+      "path": "docs/store-contract.md"
+    }
+  ],
+  "adapters": [
+    {
+      "id": "knowledge.default-store",
+      "path": "adapters/default-store/index.js",
+      "description": "Default store adapter: markdown files + YAML frontmatter + wikilinks + JSON graph index."
+    },
+    {
+      "id": "knowledge.flow-runner",
+      "path": "adapters/flow-runner/index.js",
+      "description": "Executable flow logic: capture(rawText, meta) \u2192 classified raw record; compile(rawIds[]) \u2192 compiled record with provenance links; synthesize(conceptId | topicSelector, options) \u2192 concept summary proposal with mutation gate; consolidate(snapshotId | topicSelector, options) \u2192 decision snapshot consolidation with supersede-not-delete; retire(recordId, options) \u2192 gated status lifecycle transition (active\u2192implemented\u2192retired) with working-set exclusion. Emits canonical telemetry events at gate points."
+    },
+    {
+      "id": "knowledge.similarity-vector",
+      "path": "adapters/similarity-vector/index.js",
+      "description": "Vector similarity detector: createVectorSimilarityDetector(options) returns a drop-in SimilarityDetector backed by dense embeddings and cosine similarity. Supports injectable embed fn (tests) or ollama /api/embed (default). Fail-closed: throws EMBED_FAILURE on infrastructure errors rather than silently masking them as empty clusters."
+    }
+  ],
+  "evals": [
+    {
+      "id": "knowledge.contract-suite",
+      "path": "evals/contract-suite/suite.test.js",
+      "description": "Parameterized contract test suite for any Knowledge Kit store adapter."
+    },
+    {
+      "id": "knowledge.ingest-compile-suite",
+      "path": "evals/ingest-compile/suite.test.js",
+      "description": "Eval cases for ingest (AC-mapped), compile provenance gate, telemetry emission, and ref resolution."
+    },
+    {
+      "id": "knowledge.synthesis-suite",
+      "path": "evals/synthesis/suite.test.js",
+      "description": "Eval cases for synthesize: AC1 (similar source \u2192 proposal not mutation), AC2 (rejection leaves concept byte-identical), AC3 (apply updates with provenance to all contributing sources), pluggable-similarity interface test, gate telemetry."
+    },
+    {
+      "id": "knowledge.consolidation-suite",
+      "path": "evals/consolidation/suite.test.js",
+      "description": "Eval cases for consolidate: AC1 (related event -> proposal, not mutation); AC2 (apply updates exactly ONE snapshot, links supersedes refs, superseded sources still queryable); AC3 fixture (decision changed across 3 events -> snapshot reflects ONLY latest decision, provenance to all 3); supersede-not-delete invariant; gate telemetry; contract suite extensions for snapshot semantics."
+    },
+    {
+      "id": "knowledge.similarity-vector-suite",
+      "path": "evals/similarity-vector/suite.test.js",
+      "description": "Eval cases for the vector similarity adapter: unit tests (cosineSimilarity math, injectable embed, threshold, fail-closed), drop-in proof (runner.synthesize with injected embed produces valid proposals), and live-gated tests (real ollama nomic-embed-text round-trip \u2014 skipped when ollama unavailable)."
+    },
+    {
+      "id": "knowledge.retirement-suite",
+      "path": "evals/retirement/suite.test.js",
+      "description": "Eval cases for retire: AC1 (retirement only via approved proposal with rationale/ref, transition table enforcement); AC2 (retired excluded from listByType/listByCategory/similarity defaults, returned with includeRetired flag, provenance intact via get()); AC3 (consolidation after retirement reflects pruned working set; retired record still reachable from snapshot provenance history); rejection leaves status byte-identical; gate telemetry."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",

package/src/cli/flow-kit.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
 import { assertPathContained, copyDir, isoNow, readJson, walkFiles, writeJson } from "../lib/fs.js";
 import { assertKitRepository } from "../flow-kit/validate.js";
-import { activateCodexLocal } from "../runtime-adapters.js";
+import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
 
 const REGISTRY_REL = path.join("kits", "local", "installed-kits.json");
 const REPOSITORIES_REL = path.join("kits", "local", "repositories");
@@ -112,16 +112,22 @@ function status(argv: string[]): number {
   return 0;
 }
 
+// Available adapters for the activate subcommand (Issue #32: added strands-local).
+const AVAILABLE_ADAPTERS = ["codex-local", "strands-local"];
+
 function activate(argv: string[]): number {
   const args = parseArgs(argv);
   const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
   const sourceRoot = path.resolve(flagString(args.flags, "source-root", path.resolve(path.dirname(process.argv[1]), "..")) ?? ".");
   const adapter = flagString(args.flags, "adapter");
-  if (adapter && adapter !== "codex-local") {
-    console.log(JSON.stringify({ selected_adapter: null, available_adapters: ["codex-local"], supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: codex-local`] }, null, 2));
+  if (adapter && !AVAILABLE_ADAPTERS.includes(adapter)) {
+    console.log(JSON.stringify({ selected_adapter: null, available_adapters: AVAILABLE_ADAPTERS, supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: ${AVAILABLE_ADAPTERS.join(", ")}`] }, null, 2));
     return 2;
   }
-  const result = activateCodexLocal(sourceRoot, dest);
+  // Default to codex-local for backward compatibility; strands-local is opt-in via --adapter.
+  const result = adapter === "strands-local"
+    ? activateStrandsLocal(sourceRoot, dest)
+    : activateCodexLocal(sourceRoot, dest);
   console.log(JSON.stringify(result, null, 2));
   return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }

package/src/cli/runtime-adapter.ts

@@ -1,22 +1,27 @@
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
-import { activateCodexLocal } from "../runtime-adapters.js";
+import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
+
+const AVAILABLE_ADAPTERS = ["codex-local", "strands-local"];
 
 export function main(argv = process.argv.slice(2)): number {
   const [command, ...rest] = argv;
   if (command !== "activate") {
-    console.error("usage: runtime-adapter activate [--dest DIR] [--source-root DIR] [--adapter codex-local]");
+    console.error("usage: runtime-adapter activate [--dest DIR] [--source-root DIR] [--adapter codex-local|strands-local]");
     return 2;
   }
   const args = parseArgs(rest);
   const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
   const sourceRoot = path.resolve(flagString(args.flags, "source-root", path.resolve(path.dirname(process.argv[1]), "..")) ?? ".");
   const adapter = flagString(args.flags, "adapter");
-  if (adapter && adapter !== "codex-local") {
-    console.log(JSON.stringify({ selected_adapter: null, available_adapters: ["codex-local"], supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: codex-local`] }, null, 2));
+  if (adapter && !AVAILABLE_ADAPTERS.includes(adapter)) {
+    console.log(JSON.stringify({ selected_adapter: null, available_adapters: AVAILABLE_ADAPTERS, supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: ${AVAILABLE_ADAPTERS.join(", ")}`] }, null, 2));
     return 2;
   }
-  const result = activateCodexLocal(sourceRoot, dest);
+  // Default to codex-local for backward compatibility; strands-local is opt-in via --adapter.
+  const result = adapter === "strands-local"
+    ? activateStrandsLocal(sourceRoot, dest)
+    : activateCodexLocal(sourceRoot, dest);
   console.log(JSON.stringify(result, null, 2));
   return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }

package/src/cli/telemetry-doctor.ts

@@ -82,7 +82,10 @@ function channelConfigValue(config: Config, channel: string, key: string, fallba
 
 function telemetryDataDir(dest: string): string {
   const configured = process.env.TELEMETRY_DATA_DIR;
-  return configured ? path.resolve(dest, configured) : path.resolve(dest, "..", ".telemetry");
+  // Must mirror scripts/telemetry/lib/config.sh: the sink lives INSIDE the
+  // workspace at <dest>/.telemetry. The previous "../.telemetry" duplicated
+  // the parent-escape bug fixed in config.sh on 2026-06-11.
+  return configured ? path.resolve(dest, configured) : path.resolve(dest, ".telemetry");
 }
 
 function deriveConsoleEndpoint(consoleUrl: string, explicitEndpoint: string): string {

package/src/runtime-adapters.ts

@@ -152,3 +152,38 @@ export function activateCodexLocal(sourceRoot: string, dest: string): Record<str
   generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "codex-local.activation", source_path: manifestPath.split(path.sep).join("/") });
   return { selected_adapter: "codex-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }
+
+// Decision Q3 (Issue #32): Option (a) — new adapter id "strands-local" rather than
+// loading kit flows inside FlowAgentsHooks. Rationale: activation is a workspace-prep
+// concern (reads catalog + installed kits, writes runtime files, produces diagnostics).
+// Keeping it in the CLI adapter layer maximises reuse of readKitInventory and safeSegment,
+// mirrors the codex-local pattern exactly, and keeps framework adapters free of catalog-
+// layout knowledge. The Strands steering layer then reads the written runtime files.
+export function activateStrandsLocal(sourceRoot: string, dest: string): Record<string, unknown> {
+  const inventory = readKitInventory(sourceRoot, dest);
+  // Runtime flows land at .flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json
+  // so the Strands steering context can glob for *.flow.json under this path.
+  const runtimeDir = path.join(dest, ".flow-agents", "runtime", "strands");
+  const generated: Record<string, string>[] = [];
+  const skipped: Record<string, string | null>[] = [];
+  for (const asset of inventory.assets) {
+    if (asset.asset_class !== "flows") {
+      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is diagnostic-only for strands-local" });
+      continue;
+    }
+    if (!asset.asset_id) {
+      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
+      continue;
+    }
+    const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    fs.copyFileSync(asset.source_path, output);
+    generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
+  }
+  fs.mkdirSync(runtimeDir, { recursive: true });
+  const manifest = { schema_version: "1.0", adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+  const manifestPath = path.join(runtimeDir, "activation.json");
+  writeJson(manifestPath, manifest);
+  generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "strands-local.activation", source_path: manifestPath.split(path.sep).join("/") });
+  return { selected_adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+}