@kontourai/flow-agents 0.3.0 → 0.4.0

package/kits/knowledge/evals/synthesis/suite.test.js

@@ -252,7 +252,11 @@ describe("AC2 — rejection leaves concept BYTE-IDENTICAL", () => {
       "AC2: concept body is byte-identical after rejection"
     );
 
-    // Also verify the body string in the raw file bytes has not changed
+    // Also verify the body section in the markdown file is unchanged.
+    // Note: the mutation log now correctly serializes evidence (including the
+    // proposal text in the propose log entry). We verify the BODY field is
+    // unchanged, not the entire file — the mutation log is allowed to contain
+    // the proposal text as historical evidence.
     const fileContent = fs.readFileSync(
       path.join(dir, "records", `${conceptId}.md`),
       "utf8"
@@ -261,9 +265,12 @@ describe("AC2 — rejection leaves concept BYTE-IDENTICAL", () => {
       fileContent.includes("Initial definition of API design principles."),
       "AC2: original body text is present in the backing file after rejection"
     );
+    // The body section (after the final ---) must not contain the rejected proposal.
+    // Split on the closing frontmatter delimiter to get just the body portion.
+    const bodySection = fileContent.split("\n---\n").slice(-1)[0] || "";
     assert.ok(
-      !fileContent.includes("Rejected body — should never appear in concept."),
-      "AC2: proposed body text is NOT present in the backing file after rejection"
+      !bodySection.includes("Rejected body — should never appear in concept."),
+      "AC2: proposed body text is NOT in the markdown body section after rejection"
     );
   });
 

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/kit.json

@@ -29,6 +29,11 @@
       "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": [
@@ -50,7 +55,12 @@
     {
       "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. Emits canonical telemetry events at gate points."
+      "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": [
@@ -73,6 +83,16 @@
       "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.3.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",