@kontourai/flow-agents 0.3.0 → 0.4.0

package/.github/workflows/release-please.yml

@@ -15,10 +15,22 @@ jobs:
   release-please:
     runs-on: ubuntu-latest
     steps:
+      # Release PRs authored by the default GITHUB_TOKEN (github-actions[bot])
+      # get their CI runs held as action_required on every refresh. Minting a
+      # token from the org's kontour-release-bot app makes the app the PR
+      # author, so CI runs unassisted. See kontourai/flow-agents#38.
+      - name: Mint app token
+        id: app-token
+        uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
+        with:
+          app-id: ${{ vars.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
       - name: Run release-please
         id: release
-        uses: googleapis/release-please-action@v4
+        uses: googleapis/release-please-action@v5
         with:
+          token: ${{ steps.app-token.outputs.token }}
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
 

package/AGENTS.md

@@ -1,6 +1,13 @@
 # Universal Agent Bundle (Claude Code)
 
-This bundle was generated from the canonical source in this repo. Treat the repo root as the source of truth and regenerate the bundle instead of editing exported agent files by hand.
+This bundle was generated from the canonical source in this repo. Treat the repo root as the source of truth and regenerate the bundle instead of editing exported agent files by hand. (Exception: the "Repository Conventions" section below is source-repo-specific, maintained by hand, and intentionally absent from generated bundles.)
+
+## Repository Conventions (source repo only)
+
+- **Commit messages drive releases.** Releases are automated with release-please: `feat:` bumps minor, `fix:` bumps patch, `feat!:`/`BREAKING CHANGE` bumps major; `docs:`/`chore:`/`test:`/`refactor:` don't bump. Commits without a conventional prefix are invisible to version inference — use one. Details: CONTRIBUTING.md ("Releases").
+- **Never hand-edit release PRs** (`release-please--branches--*`); they are regenerated on every push to main.
+- **Evidence hygiene:** issue/PR permalinks must pin a real commit SHA (`git rev-parse`, never typed by hand); claims about behavior need command/test evidence.
+- `.flow-agents/` runtime artifacts stay untracked; durable records belong in docs/, issues, or tracked source.
 
 ## Shared Conventions
 

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.4.0](https://github.com/kontourai/flow-agents/compare/v0.3.0...v0.4.0) (2026-06-12)
+
+
+### Features
+
+* **knowledge-kit:** gated decision retirement + working-set exclusion (S7, [#37](https://github.com/kontourai/flow-agents/issues/37)) ([40ae3fb](https://github.com/kontourai/flow-agents/commit/40ae3fb483205da6cf349265a63245bd1bb4006b))
+* **knowledge-kit:** vector similarity detector — first drop-in (I10 unparked) ([a63c6d4](https://github.com/kontourai/flow-agents/commit/a63c6d4eb122d86cf14f018dc23651043be6449a))
+
+
+### Fixes
+
+* **ci:** author release PRs via kontour-release-bot app token ([#38](https://github.com/kontourai/flow-agents/issues/38)) ([6a2c937](https://github.com/kontourai/flow-agents/commit/6a2c9376df0c07458e54066108ec17e3c9548841))
+
+
+### Documentation
+
+* repo commit/release conventions in AGENTS.md, pinned by static check ([aecd896](https://github.com/kontourai/flow-agents/commit/aecd896fb2c4a86ebe51749c2257e7b41b9cbc21))
+
 ## [0.3.0](https://github.com/kontourai/flow-agents/compare/v0.2.0...v0.3.0) (2026-06-12)
 
 

package/evals/static/test_universal_bundles.sh

@@ -286,6 +286,16 @@ else
   _fail "opencode bundle missing opencode.json"
 fi
 
+# Root AGENTS.md carries a hand-maintained "Repository Conventions" section
+# (commit/release rules for agents working in THIS repo). The rest of the
+# file mirrors generated bundle output; this pin prevents a regeneration
+# sync from silently dropping the repo-specific section.
+if grep -q "## Repository Conventions (source repo only)" "$ROOT_DIR/AGENTS.md" 2>/dev/null && grep -q "release-please" "$ROOT_DIR/AGENTS.md" 2>/dev/null; then
+  _pass "root AGENTS.md retains the Repository Conventions section"
+else
+  _fail "root AGENTS.md is missing the Repository Conventions section (regeneration clobbered it?)"
+fi
+
 # Generated hook artifacts must PARSE in their host language. The pi live
 # smoke (2026-06-11) caught the generator emitting an unterminated string
 # (template-literal escaping) that pi's loader rejected at startup.

package/kits/knowledge/adapters/default-store/index.js

@@ -167,9 +167,19 @@ function serializeYaml(obj, indent = 0) {
             const entries = Object.entries(item).filter(([, v]) => v !== undefined && v !== null);
             if (entries.length === 0) { lines.push(`${pad}  - {}`); continue; }
             const [firstKey, firstVal] = entries[0];
-            lines.push(`${pad}  - ${firstKey}: ${yamlScalar(firstVal)}`);
+            if (typeof firstVal === "object" && firstVal !== null && !Array.isArray(firstVal)) {
+              lines.push(`${pad}  - ${firstKey}:`);
+              lines.push(serializeYaml(firstVal, indent + 6));
+            } else {
+              lines.push(`${pad}  - ${firstKey}: ${yamlScalar(firstVal)}`);
+            }
             for (const [k, v] of entries.slice(1)) {
-              lines.push(`${pad}    ${k}: ${yamlScalar(v)}`);
+              if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+                lines.push(`${pad}    ${k}:`);
+                lines.push(serializeYaml(v, indent + 6));
+              } else {
+                lines.push(`${pad}    ${k}: ${yamlScalar(v)}`);
+              }
             }
           } else {
             lines.push(`${pad}  - ${yamlScalar(item)}`);
@@ -292,8 +302,16 @@ function removeLinksFromGraph(graph, sourceId) {
 // ---------------------------------------------------------------------------
 
 const VALID_TYPES = new Set(["raw", "compiled", "concept", "snapshot"]);
+const VALID_STATUSES = new Set(["active", "implemented", "retired"]);
 const CATEGORY_SEGMENT_RE = /^[a-z0-9_-]+$/;
 
+// Status transition table: from → allowed targets
+const VALID_STATUS_TRANSITIONS = {
+  active:      new Set(["implemented", "retired"]),
+  implemented: new Set(["retired"]),
+  retired:     new Set(),  // terminal — no further transitions
+};
+
 function validateCategory(cat) {
   if (!cat || typeof cat !== "string") return false;
   return cat.split(".").every((seg) => CATEGORY_SEGMENT_RE.test(seg));
@@ -376,6 +394,7 @@ export class DefaultKnowledgeStore {
       title: input.title,
       category: input.category,
       tags: input.tags || [],
+      status: "active",
       created_at: now,
       updated_at: now,
       provenance: {
@@ -526,8 +545,7 @@ export class DefaultKnowledgeStore {
 
     const concept = this._readRecord(conceptId);
     if (!concept) throw notFoundError(conceptId);
-    if (concept.type !== "concept" && concept.type !== "snapshot")
-      throw missingEvidenceError(`propose: concept_id must reference a concept or snapshot record; got type: ${concept.type}`);
+    // Any record type may receive a proposal (retire flow uses this for all types)
 
     const proposer = this._readRecord(proposerId);
     if (!proposer) throw notFoundError(proposerId);
@@ -594,8 +612,7 @@ export class DefaultKnowledgeStore {
 
     const concept = this._readRecord(conceptId);
     if (!concept) throw notFoundError(conceptId);
-    if (concept.type !== "concept" && concept.type !== "snapshot")
-      throw missingEvidenceError(`apply: concept_id must reference a concept or snapshot record; got type: ${concept.type}`);
+    // Any record type may be the apply target
 
     const proposer = this._readRecord(proposerId);
     if (!proposer) throw notFoundError(proposerId);
@@ -637,8 +654,7 @@ export class DefaultKnowledgeStore {
 
     const concept = this._readRecord(conceptId);
     if (!concept) throw notFoundError(conceptId);
-    if (concept.type !== "concept" && concept.type !== "snapshot")
-      throw missingEvidenceError(`reject: concept_id must reference a concept or snapshot record; got type: ${concept.type}`);
+    // Any record type may be the reject target
 
     const proposer = this._readRecord(proposerId);
     if (!proposer) throw notFoundError(proposerId);
@@ -759,6 +775,59 @@ export class DefaultKnowledgeStore {
   }
 
 
+  // -------------------------------------------------------------------------
+  // retire  (Addendum B — S7)
+  // -------------------------------------------------------------------------
+
+  async retire(id, targetStatus, evidence) {
+    if (!evidence?.agent)
+      throw missingEvidenceError("retire: missing required evidence field: agent");
+    if (!evidence?.rationale || !evidence.rationale.trim())
+      throw missingEvidenceError("retire: missing required evidence field: rationale");
+    if (targetStatus !== "implemented" && targetStatus !== "retired")
+      throw missingEvidenceError(
+        `retire: targetStatus must be "implemented" or "retired"; got: ${targetStatus}`
+      );
+    if (targetStatus === "implemented" && (!evidence.implementedByRef || !evidence.implementedByRef.trim()))
+      throw missingEvidenceError(
+        'retire: implementedByRef is required when targetStatus is "implemented"'
+      );
+
+    const record = this._readRecord(id);
+    if (!record) throw notFoundError(id);
+
+    const currentStatus = record.status || "active";
+    const allowed = VALID_STATUS_TRANSITIONS[currentStatus];
+    if (!allowed || !allowed.has(targetStatus)) {
+      throw missingEvidenceError(
+        `retire: invalid transition from "${currentStatus}" to "${targetStatus}"`
+      );
+    }
+
+    const now = this._now();
+    const updated = {
+      ...record,
+      status: targetStatus,
+      updated_at: now,
+      mutation_log: [
+        ...(record.mutation_log || []),
+        {
+          op: "retire",
+          at: now,
+          agent: evidence.agent,
+          ...(evidence.note ? { note: evidence.note } : {}),
+          evidence: {
+            targetStatus,
+            rationale: evidence.rationale,
+            ...(evidence.implementedByRef ? { implementedByRef: evidence.implementedByRef } : {}),
+            ...(evidence.supersededByRef ? { supersededByRef: evidence.supersededByRef } : {}),
+          },
+        },
+      ],
+    };
+    this._writeRecord(updated);
+  }
+
   // -------------------------------------------------------------------------
   // get
   // -------------------------------------------------------------------------
@@ -785,20 +854,32 @@ export class DefaultKnowledgeStore {
 
   async listByCategory(category, options = {}) {
     const records = this._allRecords();
+    const includeRetired = options.includeRetired === true;
     if (options.prefix) {
       return records.filter(
-        (r) => r.category === category || r.category.startsWith(`${category}.`)
+        (r) =>
+          (r.category === category || r.category.startsWith(`${category}.`)) &&
+          (includeRetired || (r.status || "active") !== "retired")
       );
     }
-    return records.filter((r) => r.category === category);
+    return records.filter(
+      (r) =>
+        r.category === category &&
+        (includeRetired || (r.status || "active") !== "retired")
+    );
   }
 
   // -------------------------------------------------------------------------
   // listByType
   // -------------------------------------------------------------------------
 
-  async listByType(type) {
-    return this._allRecords().filter((r) => r.type === type);
+  async listByType(type, options = {}) {
+    const includeRetired = options.includeRetired === true;
+    return this._allRecords().filter(
+      (r) =>
+        r.type === type &&
+        (includeRetired || (r.status || "active") !== "retired")
+    );
   }
 
   // -------------------------------------------------------------------------

package/kits/knowledge/adapters/flow-runner/index.js

@@ -13,6 +13,7 @@
  *   - compile(rawIds[], options)        — compile flow: select → compile → link with provenance
  *   - synthesize(conceptId | topicSelector, options) — synthesize flow:
  *       detect-cluster → propose → evidence-gate → apply-or-reject
+ *   - retire(recordId, options)          — retire flow: identify → propose → evidence-gate → apply-or-reject
  *   - defaultSimilarityDetector         — pluggable similarity interface default (R3)
  *
  * Telemetry:
@@ -112,6 +113,9 @@ export async function defaultSimilarityDetector(concept, candidates, store) {
   const similar = [];
 
   for (const candidate of candidates) {
+    // Exclude retired records from the working set (Addendum B — R3)
+    if ((candidate.status || "active") === "retired") continue;
+
     // Check 1: category overlap (prefix match in either direction)
     const catMatch =
       candidate.category === concept.category ||
@@ -1107,6 +1111,278 @@ export class KnowledgeFlowRunner {
     };
   }
 
+  // -------------------------------------------------------------------------
+  // knowledge.retire flow  (Addendum B — S7)
+  //   Steps: identify → propose-retirement → evidence-gate → apply-or-reject → done
+  //   Gate: evidence-gate — proposal carries rationale/ref; no direct mutation (AC1).
+  //         apply-gate    — apply or reject via store retire op.
+  //                         rejection leaves record status byte-identical (AC2).
+  //
+  // Machinery reuse: retire shares the same propose→evidence-gate→apply-or-reject
+  // pattern as synthesize/consolidate. The store's retire op enforces the transition
+  // table; rejection leaves the record unchanged.
+  // -------------------------------------------------------------------------
+
+  /**
+   * Execute the retire flow: identify the target record, create a retirement
+   * proposal (never a direct mutation), gate the evidence, then apply or reject.
+   *
+   * On apply:
+   *   The store retire op updates the record status to targetStatus and appends
+   *   a mutation log entry with the full evidence. The record is excluded from
+   *   default working-set queries (listByType, listByCategory, similarity
+   *   detection) unless includeRetired is true.
+   *
+   * On reject:
+   *   The record status is byte-identical to its pre-proposal state.
+   *
+   * @param {string} recordId
+   *   ID of the record to retire.
+   * @param {object} [options]
+   *   - targetStatus: "implemented"|"retired"  — target status (required)
+   *   - rationale: string                      — why retiring (required)
+   *   - implementedByRef: string               — ref when targetStatus="implemented" (required)
+   *   - supersededByRef: string                — optional ref to superseding artifact
+   *   - decision: "apply"|"reject"             — gate decision (default "apply")
+   *   - rejectReason: string                   — reason for rejection (required when decision="reject")
+   *   - agent: string                          — override agent name
+   *   - session_id: string                     — session id
+   *   - note: string                           — provenance note
+   * @returns {Promise<{
+   *   recordId: string,
+   *   targetStatus: string,
+   *   decision: "apply"|"reject",
+   *   previousStatus: string,
+   *   proposerId: string,
+   *   telemetryEvents: object[]
+   * }>}
+   */
+  async retire(recordId, options = {}) {
+    const events = [];
+    const agent = options.agent || this._agent;
+
+    // ── Step: identify ─────────────────────────────────────────────────────
+    if (!recordId || typeof recordId !== "string") {
+      throw missingEvidenceError("retire: recordId must be a non-empty string");
+    }
+
+    const targetStatus = options.targetStatus;
+    if (targetStatus !== "implemented" && targetStatus !== "retired") {
+      throw missingEvidenceError(
+        'retire: options.targetStatus must be "implemented" or "retired"'
+      );
+    }
+
+    if (!options.rationale || !options.rationale.trim()) {
+      throw missingEvidenceError("retire: options.rationale is required");
+    }
+
+    if (targetStatus === "implemented" && (!options.implementedByRef || !options.implementedByRef.trim())) {
+      throw missingEvidenceError(
+        'retire: options.implementedByRef is required when targetStatus is "implemented"'
+      );
+    }
+
+    const record = await this._store.get(recordId);
+    if (!record) {
+      throw missingEvidenceError(`retire: record not found: ${recordId}`);
+    }
+
+    const previousStatus = record.status || "active";
+
+    // Validate transition early (surface errors at identify-gate, not at apply-gate)
+    const VALID_TRANSITIONS = {
+      active:      new Set(["implemented", "retired"]),
+      implemented: new Set(["retired"]),
+      retired:     new Set(),
+    };
+    const allowed = VALID_TRANSITIONS[previousStatus] || new Set();
+    if (!allowed.has(targetStatus)) {
+      throw missingEvidenceError(
+        `retire: invalid transition from "${previousStatus}" to "${targetStatus}"`
+      );
+    }
+
+    // Emit identify gate entry
+    const identifyGateIn = this._telemetry.emitGate("knowledge.retire", "identify-gate", {
+      flow: "knowledge.retire",
+      gate: "identify-gate",
+      record_id: recordId,
+      record_type: record.type,
+      current_status: previousStatus,
+      target_status: targetStatus,
+    });
+    events.push(identifyGateIn);
+
+    const identifyGateOut = this._telemetry.emitGateResult("knowledge.retire", "identify-gate", {
+      record_id: recordId,
+      record_type: record.type,
+      current_status: previousStatus,
+      target_status: targetStatus,
+      transition_valid: true,
+    });
+    events.push(identifyGateOut);
+
+    // ── Step: propose-retirement ───────────────────────────────────────────
+    // We reuse the store's propose op against the record itself.
+    // The record acts as the "concept" target; a transient proposer raw record
+    // carries the retirement proposal and proposes link.
+
+    const proposeGateIn = this._telemetry.emitGate(
+      "knowledge.retire",
+      "propose-retirement-gate",
+      {
+        flow: "knowledge.retire",
+        gate: "propose-retirement-gate",
+        record_id: recordId,
+        target_status: targetStatus,
+        rationale: options.rationale,
+      }
+    );
+    events.push(proposeGateIn);
+
+    // Create a transient proposer record to hold the retirement proposal
+    const proposerBody =
+      `Retirement proposal for record ${recordId}.
+` +
+      `Target status: ${targetStatus}
+` +
+      `Rationale: ${options.rationale}
+` +
+      (options.implementedByRef ? `Implemented-by: ${options.implementedByRef}
+` : "") +
+      (options.supersededByRef ? `Superseded-by: ${options.supersededByRef}
+` : "");
+
+    const proposerId = await this._store.create({
+      type: "raw",
+      title: `Retirement proposal: ${record.title}`,
+      body: proposerBody,
+      category: record.category,
+      provenance: {
+        agent,
+        note: `Retirement proposal for ${recordId}`,
+        ...(options.session_id ? { session_id: options.session_id } : {}),
+      },
+    });
+
+    // Attach the proposal via the store's propose op (not direct mutation — AC1)
+    await this._store.propose(recordId, proposerId, {
+      agent,
+      proposal: options.rationale,
+      ...(options.note ? { note: options.note } : {}),
+    });
+
+    const proposeGateOut = this._telemetry.emitGateResult(
+      "knowledge.retire",
+      "propose-retirement-gate",
+      {
+        record_id: recordId,
+        proposer_id: proposerId,
+        target_status: targetStatus,
+        proposal_recorded: true,
+      }
+    );
+    events.push(proposeGateOut);
+
+    // ── Step: evidence-gate ────────────────────────────────────────────────
+    // Verify the proposal carries required evidence and the transition is valid.
+
+    const evidenceGateIn = this._telemetry.emitGate("knowledge.retire", "evidence-gate", {
+      flow: "knowledge.retire",
+      gate: "evidence-gate",
+      record_id: recordId,
+      proposer_id: proposerId,
+      target_status: targetStatus,
+    });
+    events.push(evidenceGateIn);
+
+    // Enforce: proposer must have a "proposes" link to the record
+    const { forward } = await this._store.getLinks(proposerId);
+    const hasProposesLink = forward.some(
+      (l) => l.target_id === recordId && l.kind === "proposes"
+    );
+    if (!hasProposesLink) {
+      throw missingEvidenceError(
+        `evidence-gate: proposer ${proposerId} must have a "proposes" link to record ${recordId}`
+      );
+    }
+
+    // Enforce: target record still exists
+    const targetRecord = await this._store.get(recordId);
+    if (!targetRecord) {
+      throw missingEvidenceError(
+        `evidence-gate: target record ${recordId} does not exist`
+      );
+    }
+
+    const evidenceGateOut = this._telemetry.emitGateResult("knowledge.retire", "evidence-gate", {
+      record_id: recordId,
+      proposer_id: proposerId,
+      target_status: targetStatus,
+      proposes_link_verified: true,
+      target_record_verified: true,
+    });
+    events.push(evidenceGateOut);
+
+    // ── Step: apply-or-reject ──────────────────────────────────────────────
+    const decision = options.decision || "apply";
+
+    const applyGateIn = this._telemetry.emitGate("knowledge.retire", "apply-gate", {
+      flow: "knowledge.retire",
+      gate: "apply-gate",
+      record_id: recordId,
+      proposer_id: proposerId,
+      target_status: targetStatus,
+      decision,
+    });
+    events.push(applyGateIn);
+
+    if (decision === "apply") {
+      // Apply via store retire op — transitions status, appends mutation log (AC1)
+      await this._store.retire(recordId, targetStatus, {
+        agent,
+        rationale: options.rationale,
+        ...(options.implementedByRef ? { implementedByRef: options.implementedByRef } : {}),
+        ...(options.supersededByRef ? { supersededByRef: options.supersededByRef } : {}),
+        ...(options.note ? { note: options.note } : {}),
+      });
+    } else if (decision === "reject") {
+      if (!options.rejectReason || !options.rejectReason.trim()) {
+        throw missingEvidenceError(
+          "apply-gate: options.rejectReason is required when decision=reject"
+        );
+      }
+      // Reject via store reject op — record status remains untouched (AC2)
+      await this._store.reject(recordId, proposerId, {
+        agent,
+        reason: options.rejectReason,
+      });
+    } else {
+      throw missingEvidenceError(
+        `apply-gate: decision must be "apply" or "reject"; got: ${decision}`
+      );
+    }
+
+    const applyGateOut = this._telemetry.emitGateResult("knowledge.retire", "apply-gate", {
+      record_id: recordId,
+      proposer_id: proposerId,
+      target_status: targetStatus,
+      decision,
+      previous_status: previousStatus,
+    });
+    events.push(applyGateOut);
+
+    return {
+      recordId,
+      targetStatus,
+      decision,
+      previousStatus,
+      proposerId,
+      telemetryEvents: events,
+    };
+  }
+
 }
 
 // ---------------------------------------------------------------------------
@@ -1176,4 +1452,18 @@ export async function consolidate(
   return runner.consolidate(snapshotIdOrTopic, consolidateOpts);
 }
 
+/**
+ * Module-level retire: creates an ephemeral runner using the provided store.
+ *
+ * @param {string} recordId
+ * @param {object} options  (merged into retire options + runner options)
+ */
+export async function retire(
+  recordId,
+  { store, workspace, agent, sessionId, ...retireOpts } = {}
+) {
+  const runner = new KnowledgeFlowRunner({ store, workspace, agent, sessionId });
+  return runner.retire(recordId, retireOpts);
+}
+
 export default KnowledgeFlowRunner;