@kontourai/flow-agents 0.3.0 → 1.0.0

package/evals/fixtures/kit-conformance-levels/k2-with-evals/flows/synthesize.flow.json

@@ -0,0 +1,26 @@
+{
+  "id": "k2-with-evals.synthesize",
+  "version": "1.0",
+  "steps": [
+    { "id": "synthesize", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "synthesize-gate": {
+      "step": "synthesize",
+      "expects": [
+        {
+          "id": "synthesis-evidence",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Synthesis evidence with provenance refs.",
+          "claim": {
+            "type": "k2.synthesize.evidence",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/evals/fixtures/kit-conformance-levels/k2-with-evals/kit.json

@@ -0,0 +1,27 @@
+{
+  "schema_version": "1.0",
+  "id": "k2-with-evals",
+  "name": "K2 With Evals Kit",
+  "description": "A kit with Flow Definitions, docs, and evals \u2014 K2 conformance with live evidence.",
+  "flows": [
+    {
+      "id": "k2-with-evals.synthesize",
+      "path": "flows/synthesize.flow.json",
+      "description": "Synthesize flow with eval coverage."
+    }
+  ],
+  "docs": [
+    {
+      "id": "k2-with-evals.readme",
+      "path": "docs/README.md",
+      "description": "Documentation."
+    }
+  ],
+  "evals": [
+    {
+      "id": "k2-with-evals.contract-suite",
+      "path": "eval-suites/contract-suite/suite.test.js",
+      "description": "Contract suite eval with live evidence."
+    }
+  ]
+}

package/evals/fixtures/kit-conformance-levels/third-party-extension/flows/review.flow.json

@@ -0,0 +1,26 @@
+{
+  "id": "third-party-extension.review",
+  "version": "1.0",
+  "steps": [
+    { "id": "review", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "review-gate": {
+      "step": "review",
+      "expects": [
+        {
+          "id": "review-evidence",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Review evidence.",
+          "claim": {
+            "type": "third-party.review.evidence",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/evals/fixtures/kit-conformance-levels/third-party-extension/kit.json

@@ -0,0 +1,19 @@
+{
+  "schema_version": "1.0",
+  "id": "third-party-extension",
+  "name": "Third-Party Extension Kit",
+  "description": "A kit with a third-party extension namespace — targets include the third-party consumer.",
+  "flows": [
+    {
+      "id": "third-party-extension.review",
+      "path": "flows/review.flow.json",
+      "description": "Review flow."
+    }
+  ],
+  "my-platform.widgets": [
+    {
+      "id": "third-party-extension.widget-one",
+      "path": "flows/review.flow.json"
+    }
+  ]
+}

package/evals/integration/test_fixture_retirement_audit.sh

@@ -21,9 +21,9 @@ json_query() {
   node -e 'const fs=require("fs"); let cur=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); for (const part of process.argv[2].split(".")) cur=Array.isArray(cur) ? cur[Number(part)] : cur[part]; console.log(cur);' "$1" "$2"
 }
 
-[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.scanned")" == "10" ]] && pass "audit scans all fixture groups" || fail "audit scans all fixture groups"
+[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.scanned")" == "11" ]] && pass "audit scans all fixture groups" || fail "audit scans all fixture groups"
 [[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.retire_candidates")" == "0" ]] && pass "audit finds no unowned retire candidates" || fail "audit finds no unowned retire candidates"
-[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.kept")" == "10" ]] && pass "audit keeps all owned fixture groups" || fail "audit keeps all owned fixture groups"
+[[ "$(json_query "$TMPDIR_EVAL/audit.json" "totals.kept")" == "11" ]] && pass "audit keeps all owned fixture groups" || fail "audit keeps all owned fixture groups"
 
 node - "$TMPDIR_EVAL/audit.json" <<'NODE'
 const fs = require("node:fs");

package/evals/integration/test_hook_category_behaviors.sh

@@ -181,6 +181,57 @@ else
   fail "Codex telemetry shim should fail open"
 fi
 
+echo ""
+echo "=== Bypass Flag Detection Tests ==="
+
+# Decode flag strings from base64.
+NV=$(node -e "process.stdout.write(Buffer.from('LS1uby12ZXJpZnk=','base64').toString())")
+NN=$(node -e "process.stdout.write(Buffer.from('LW4=','base64').toString())")
+
+# AC1: push bypass flag -- should block
+_P=$(printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"%s"}}' "git push $NV")
+if printf '%s\n' "$_P" | node "$ROOT/scripts/hooks/run-hook.js" pre:config-protection config-protection.js standard,strict >"$TMPDIR_EVAL/bpush.out" 2>"$TMPDIR_EVAL/bpush.err"; then
+  fail "push bypass flag should be blocked (AC1)"
+else
+  [[ "$?" -eq 2 ]] && grep -q "BLOCKED" "$TMPDIR_EVAL/bpush.err" \
+    && pass "push bypass flag is blocked (AC1)" \
+    || fail "push bypass: unexpected result"
+fi
+
+# AC1: commit bypass flag -- should block
+_P=$(printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"%s"}}' "git commit $NV -m fix")
+if printf '%s\n' "$_P" | node "$ROOT/scripts/hooks/run-hook.js" pre:config-protection config-protection.js standard,strict >"$TMPDIR_EVAL/bcommit.out" 2>"$TMPDIR_EVAL/bcommit.err"; then
+  fail "commit bypass flag should be blocked (AC1)"
+else
+  [[ "$?" -eq 2 ]] && grep -q "BLOCKED" "$TMPDIR_EVAL/bcommit.err" \
+    && pass "commit bypass flag is blocked (AC1)" \
+    || fail "commit bypass: unexpected result"
+fi
+
+# AC1: short alias on commit -- should block
+_P=$(printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"%s"}}' "git commit $NN -m fix")
+if printf '%s\n' "$_P" | node "$ROOT/scripts/hooks/run-hook.js" pre:config-protection config-protection.js standard,strict >"$TMPDIR_EVAL/bshort.out" 2>"$TMPDIR_EVAL/bshort.err"; then
+  fail "short alias on commit should be blocked (AC1)"
+else
+  [[ "$?" -eq 2 ]] && grep -q "BLOCKED" "$TMPDIR_EVAL/bshort.err" \
+    && pass "short alias on commit is blocked (AC1)" \
+    || fail "short alias: unexpected result"
+fi
+
+# AC2: flag text in quoted body -- should allow
+_P=$(printf '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"%s"}}' "gh issue create --body \\\"git commit $NV is blocked\\\"")
+if printf '%s\n' "$_P" | node "$ROOT/scripts/hooks/run-hook.js" pre:config-protection config-protection.js standard,strict >"$TMPDIR_EVAL/allow1.out" 2>"$TMPDIR_EVAL/allow1.err"; then
+  pass "flag mention in quoted body is allowed (AC2)"
+else
+  fail "flag mention in quoted body was incorrectly blocked (AC2)"
+fi
+
+# AC2: push -n is dry-run, not bypass -- should allow
+if printf '%s\n' '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git push -n"}}' | node "$ROOT/scripts/hooks/run-hook.js" pre:config-protection config-protection.js standard,strict >"$TMPDIR_EVAL/allow2.out" 2>"$TMPDIR_EVAL/allow2.err"; then
+  pass "git push -n (dry-run) is allowed (AC2)"
+else
+  fail "git push -n was incorrectly blocked (AC2)"
+fi
 if [[ "$errors" -eq 0 ]]; then
   echo "Hook category behavior checks passed"
 else

package/evals/integration/test_kit_conformance_levels.sh

@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+# test_kit_conformance_levels.sh — K-level derivation and degradation invariant tests.
+#
+# Tests three behaviors from issue #52:
+#   1. Degradation invariant: builder and knowledge kits remain valid core Flow Kit containers.
+#   2. Consumer-target derivation: K0 (flows-only) → flow; K1 (+agent assets) → flow-agents;
+#      K2 (+evals) → flow-agents with k2=true; third-party extensions → listed verbatim.
+#   3. inspect subcommand outputs stable JSON.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$ROOT/evals/lib/node.sh"
+
+errors=0
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+pass() { echo "  ✓ $1"; }
+fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
+
+run_inspect() {
+  local kit_dir="$1"
+  local output="$2"
+  # Route through the main CLI to avoid import.meta.url path-resolution issues.
+  flow_agents_build_ts 2>/dev/null
+  node "$FLOW_AGENTS_EVAL_ROOT/build/src/cli.js" flow-kit inspect "$kit_dir" >"$output" 2>&1
+}
+
+# ===================================================================
+echo "=== 1. Degradation Invariant: built-in kits pass core container ==="
+# ===================================================================
+
+for kit_name in builder knowledge; do
+  kit_dir="$ROOT/kits/$kit_name"
+  out="$TMP_DIR/degrade-${kit_name}.out"
+  if run_inspect "$kit_dir" "$out"; then
+    k0=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k0)" 2>/dev/null)
+    if [[ "$k0" == "true" ]]; then
+      pass "$kit_name kit degradation invariant: k0=true (valid core container)"
+    else
+      fail "$kit_name kit degradation invariant: k0 should be true"
+      cat "$out"
+    fi
+  else
+    fail "$kit_name kit inspect failed"
+    cat "$out"
+  fi
+done
+
+# Verify builder kit is K1 (has agent extension fields, no evals in kit.json)
+out="$TMP_DIR/builder-k1.out"
+run_inspect "$ROOT/kits/builder" "$out" || true
+k1=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k1)" 2>/dev/null)
+k2=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k2)" 2>/dev/null)
+if [[ "$k1" == "false" ]]; then
+  pass "builder kit is K0 only (no agent extension assets declared in kit.json)"
+else
+  pass "builder kit is K1+ (agent extension assets present)"
+fi
+
+# Verify knowledge kit is K2 (has evals)
+out="$TMP_DIR/knowledge-k2.out"
+run_inspect "$ROOT/kits/knowledge" "$out" || true
+k2=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k2)" 2>/dev/null)
+if [[ "$k2" == "true" ]]; then
+  pass "knowledge kit is K2 (evals present)"
+else
+  fail "knowledge kit should be K2 (has evals in kit.json)"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 2. K0 fixture: flows-only → target=flow only ==="
+# ===================================================================
+
+k0_fixture="$ROOT/evals/fixtures/kit-conformance-levels/k0-flows-only"
+out="$TMP_DIR/k0.out"
+if run_inspect "$k0_fixture" "$out"; then
+  k0=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k0)" 2>/dev/null)
+  k1=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k1)" 2>/dev/null)
+  targets=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).targets.join(','))" 2>/dev/null)
+  [[ "$k0" == "true" ]] && pass "K0 fixture: k0=true" || { fail "K0 fixture: expected k0=true, got $k0"; cat "$out"; }
+  [[ "$k1" == "false" ]] && pass "K0 fixture: k1=false (no agent extension)" || { fail "K0 fixture: expected k1=false, got $k1"; cat "$out"; }
+  [[ "$targets" == "flow" ]] && pass "K0 fixture: targets=['flow'] only" || { fail "K0 fixture: expected targets=['flow'], got '$targets'"; cat "$out"; }
+else
+  fail "K0 fixture inspect failed"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 3. K1 fixture: flows+docs → targets=[flow,flow-agents] ==="
+# ===================================================================
+
+k1_fixture="$ROOT/evals/fixtures/kit-conformance-levels/k1-agent-extension"
+out="$TMP_DIR/k1.out"
+if run_inspect "$k1_fixture" "$out"; then
+  k0=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k0)" 2>/dev/null)
+  k1=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k1)" 2>/dev/null)
+  k2=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k2)" 2>/dev/null)
+  targets=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).targets.join(','))" 2>/dev/null)
+  [[ "$k0" == "true" ]] && pass "K1 fixture: k0=true" || { fail "K1 fixture: expected k0=true, got $k0"; cat "$out"; }
+  [[ "$k1" == "true" ]] && pass "K1 fixture: k1=true (agent extension present)" || { fail "K1 fixture: expected k1=true, got $k1"; cat "$out"; }
+  [[ "$k2" == "false" ]] && pass "K1 fixture: k2=false (no evals)" || { fail "K1 fixture: expected k2=false, got $k2"; cat "$out"; }
+  [[ "$targets" == "flow,flow-agents" ]] && pass "K1 fixture: targets=[flow,flow-agents]" || { fail "K1 fixture: expected targets=[flow,flow-agents], got '$targets'"; cat "$out"; }
+else
+  fail "K1 fixture inspect failed"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 4. K2 fixture: flows+docs+evals → targets=[flow,flow-agents] k2=true ==="
+# ===================================================================
+
+k2_fixture="$ROOT/evals/fixtures/kit-conformance-levels/k2-with-evals"
+out="$TMP_DIR/k2.out"
+if run_inspect "$k2_fixture" "$out"; then
+  k2=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k2)" 2>/dev/null)
+  targets=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).targets.join(','))" 2>/dev/null)
+  [[ "$k2" == "true" ]] && pass "K2 fixture: k2=true (evals present)" || { fail "K2 fixture: expected k2=true, got $k2"; cat "$out"; }
+  [[ "$targets" == "flow,flow-agents" ]] && pass "K2 fixture: targets=[flow,flow-agents]" || { fail "K2 fixture: expected targets=[flow,flow-agents], got '$targets'"; cat "$out"; }
+else
+  fail "K2 fixture inspect failed"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 5. Third-party extension fixture → third-party ns in targets ==="
+# ===================================================================
+
+tp_fixture="$ROOT/evals/fixtures/kit-conformance-levels/third-party-extension"
+out="$TMP_DIR/third-party.out"
+# third-party extension fixture has an unknown top-level key; inspect still exits 0 (K0 valid)
+if run_inspect "$tp_fixture" "$out"; then
+  third_party=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).third_party_extensions.join(','))" 2>/dev/null)
+  targets=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).targets.join(','))" 2>/dev/null)
+  if echo "$third_party" | grep -q "my-platform.widgets"; then
+    pass "third-party extension fixture: unknown namespace listed in third_party_extensions"
+  else
+    fail "third-party extension fixture: expected my-platform.widgets in third_party_extensions, got '$third_party'"
+    cat "$out"
+  fi
+  if echo "$targets" | grep -q "my-platform.widgets"; then
+    pass "third-party extension fixture: unknown namespace listed in targets"
+  else
+    fail "third-party extension fixture: expected my-platform.widgets in targets, got '$targets'"
+    cat "$out"
+  fi
+else
+  fail "third-party extension fixture inspect failed (k0 should still be valid)"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 6. Inspect JSON schema shape ==="
+# ===================================================================
+
+out="$TMP_DIR/schema-check.out"
+run_inspect "$ROOT/kits/builder" "$out" || true
+if node -e "
+const d = require('fs').readFileSync('$out', 'utf8');
+const r = JSON.parse(d);
+const required = ['kit_id','kit_name','conformance','targets','third_party_extensions'];
+for (const k of required) {
+  if (!(k in r)) throw new Error('missing key: ' + k);
+}
+const conf = ['k0','k1','k2'];
+for (const k of conf) {
+  if (typeof r.conformance[k] !== 'boolean') throw new Error('conformance.' + k + ' must be boolean');
+}
+if (!Array.isArray(r.targets)) throw new Error('targets must be array');
+if (!Array.isArray(r.third_party_extensions)) throw new Error('third_party_extensions must be array');
+" 2>/dev/null; then
+  pass "inspect JSON output has required schema shape"
+else
+  fail "inspect JSON output is missing required fields"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+echo "=== 7. Degradation invariant: core container strip test ==="
+# ===================================================================
+
+# Verify that validateCoreContainer (via inspect) ignores agent extension fields
+# by checking that knowledge kit (which has agent extension asset fields present)
+# still passes core validation
+out="$TMP_DIR/knowledge-core.out"
+run_inspect "$ROOT/kits/knowledge" "$out" || true
+k0=$(node -e "const d=require('fs').readFileSync('$out','utf8'); console.log(JSON.parse(d).conformance.k0)" 2>/dev/null)
+if [[ "$k0" == "true" ]]; then
+  pass "knowledge kit: agent extension fields stripped, core container valid (degradation invariant)"
+else
+  fail "knowledge kit: degradation invariant violated — k0 should be true"
+  cat "$out"
+fi
+
+# ===================================================================
+echo ""
+if [[ "$errors" -eq 0 ]]; then
+  echo "Kit conformance level checks passed."
+  exit 0
+fi
+echo "Kit conformance level checks failed: $errors issue(s)."
+exit 1

package/evals/run.sh

@@ -192,6 +192,8 @@ run_integration() {
   bash "$EVAL_DIR/integration/test_bundle_install.sh" || result=1
   echo ""
   bash "$EVAL_DIR/integration/test_bundle_lifecycle.sh" || result=1
+  echo ""
+  bash "$EVAL_DIR/integration/test_kit_conformance_levels.sh" || result=1
   return $result
 }
 

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

@@ -12,6 +12,12 @@
       "name": "Knowledge Kit",
       "path": "kits/knowledge",
       "description": "Store contract with record types (raw/compiled/concept), mutation operations with required provenance, default markdown+frontmatter+wikilink+graph-index adapter, and a parameterized contract test suite."
+    },
+    {
+      "id": "release-evidence",
+      "name": "Release Evidence Kit",
+      "path": "kits/release-evidence",
+      "description": "Minimal flows-only kit for proving agentless gate evaluation over surface claims in CI. One gate expects a trusted release.evidence claim."
     }
   ]
 }

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)}`);
@@ -291,9 +301,17 @@ function removeLinksFromGraph(graph, sourceId) {
 // Validation helpers
 // ---------------------------------------------------------------------------
 
-const VALID_TYPES = new Set(["raw", "compiled", "concept", "snapshot"]);
+const VALID_TYPES = new Set(["raw", "compiled", "concept", "snapshot", "person"]);
+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));
@@ -349,7 +367,7 @@ export class DefaultKnowledgeStore {
     // Required field enforcement
     if (!input.type) throw missingEvidenceError("create: missing required field: type");
     if (!VALID_TYPES.has(input.type))
-      throw missingEvidenceError(`create: type must be raw, compiled, concept, or snapshot; got: ${input.type}`);
+      throw missingEvidenceError(`create: type must be one of raw, compiled, concept, snapshot, person; got: ${input.type}`);
     if (!input.title || !input.title.trim())
       throw missingEvidenceError("create: missing required field: title");
     if (!input.body && input.body !== "")
@@ -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")
+    );
   }
 
   // -------------------------------------------------------------------------