@kontourai/flow-agents 2.3.0 → 3.0.0

package/build/src/cli/workflow-artifact-cleanup-audit.js

@@ -16,7 +16,7 @@ const ACTIVE_STATUSES = new Set([
 const KNOWN_LEARNING_STATUSES = new Set(["pending", "learned", "followup_required", "blocked"]);
 const KNOWN_LEARNING_ROUTE_TARGETS = new Set(["rule", "skill", "power", "agent", "eval", "doc", "backlog", "knowledge", "none"]);
 const KNOWN_LEARNING_ROUTE_STATUSES = new Set(["completed", "open", "deferred", "accepted", "rejected"]);
-const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history"]);
+const SKIPPED_ROOT_ENTRIES = new Set(["archive", "changes", "delivery-history", "liveness"]);
 const MAX_SIDECAR_BYTES = 1024 * 1024;
 function printHelp() {
     console.log("Usage: flow-agents workflow-artifact-cleanup-audit [--artifact-root <path>] [--json]");
@@ -24,7 +24,7 @@ function printHelp() {
     console.log("Read-only dry-run audit for local workflow artifact directories.");
     console.log("");
     console.log("Options:");
-    console.log("  --artifact-root <path>  Local artifact root to scan (default: .kontourai/flow-agents, with .flow-agents read fallback)");
+    console.log("  --artifact-root <path>  Local artifact root to scan (default: .kontourai/flow-agents)");
     console.log("  --json                  Print stable JSON buckets instead of text");
     console.log("  --help                  Show this help");
     console.log("");
@@ -148,6 +148,34 @@ function invalidItem(slug, workflowPath, reason) {
         reasons: [reason],
     };
 }
+// Promote-then-archive gate (issue #312). A delivered session's durable residue
+// (decisions, vocabulary, learnings, doc updates) must be PROMOTED before the session
+// is archived. Promotion is recorded as a session-local promotion claim in the session
+// trust.bundle (workflow-sidecar promote), detectable here via claim.metadata.promotion
+// — no new manifest entry required. A delivered/accepted session that reached a terminal
+// shape WITHOUT that claim is a cleanup_candidate (blocked from archive) with a remedy
+// naming the promote step. Already-`archived` sessions are past the gate and are never
+// re-flagged (issue #312 non-goal: do not backfill already-archived sessions).
+const PROMOTE_REMEDY = "run `flow-agents workflow-sidecar promote <dir> --evidence-path <durable-doc> ...`" +
+    " (or `promote --none --reason \"<why nothing durable>\"`) to record the promotion claim before archiving";
+function hasPromotionClaim(workflowDir) {
+    const bundlePath = path.join(workflowDir, "trust.bundle");
+    if (!fs.existsSync(bundlePath))
+        return false;
+    const parsed = readJson(bundlePath, "trust.bundle");
+    if (!parsed.ok)
+        return false;
+    const bundle = objectValue(parsed.value);
+    if (!bundle || !Array.isArray(bundle.claims))
+        return false;
+    return bundle.claims.some((entry) => {
+        const claim = objectValue(entry);
+        if (!claim)
+            return false;
+        const meta = objectValue(claim.metadata);
+        return meta !== null && objectValue(meta.promotion) !== null;
+    });
+}
 function classifyWorkflow(slug, workflowPath) {
     const statePath = path.join(workflowPath, "state.json");
     if (!fs.existsSync(statePath))
@@ -185,9 +213,15 @@ function classifyWorkflow(slug, workflowPath) {
         return { ...base, classification: "cleanup_candidate", reasons: ["verified workflow has next_action.status done"] };
     }
     if (["delivered", "accepted", "archived"].includes(status) && phase === "done") {
+        if (status !== "archived" && !hasPromotionClaim(workflowPath)) {
+            return { ...base, classification: "cleanup_candidate", reasons: [`${status} workflow reached phase done without a promotion claim; ${PROMOTE_REMEDY}`] };
+        }
         return { ...base, classification: "terminal_done", reasons: [`${status} workflow is in phase done`] };
     }
     if ((status === "accepted" || status === "archived") && learning.reasons.length === 0) {
+        if (status !== "archived" && !hasPromotionClaim(workflowPath)) {
+            return { ...base, classification: "cleanup_candidate", reasons: [`${status} workflow has closed learning routing but no promotion claim; ${PROMOTE_REMEDY}`] };
+        }
         return { ...base, classification: "terminal_done", reasons: [`${status} workflow has no open learning routing`] };
     }
     return { ...base, classification: "invalid", reasons: [`unrecognized lifecycle shape: status=${status}, phase=${phase}, next_action.status=${nextStatus ?? "missing"}`] };

package/build/src/cli/workflow-sidecar.d.ts

@@ -80,7 +80,7 @@ type SurfaceModule = {
         status: string;
         policyId: string | undefined;
     };
-    generateClaimId: (subjectId: string, surface: string, fieldOrBehavior: string) => string;
+    generateClaimId: (subjectId: string, facet: string, fieldOrBehavior: string) => string;
     statusFunctionVersion: string;
     resolveInquiry: (bundle: Record<string, unknown>, inquiry: SurfaceInquiry, options?: {
         now?: Date;
@@ -208,10 +208,17 @@ export declare function sealTrustCheckpoint(dir: string, slug: string, sealedAt:
  * trust.checkpoint.intoto.json / trust.checkpoint.sig.json from the
  * session artifact dir to <repoRoot>/delivery/.
  *
- * Fail-soft: if trust.bundle is absent, returns without throwing.
+ * Fail-soft on a missing bundle: if trust.bundle is absent, returns without throwing.
+ * Fail-CLOSED on repo-root resolution: repoRoot must be a real, resolved kits/ ancestor
+ * (see findRepoRootFromDirStrict) — null (no ancestor found) skips the publish with a
+ * visible warning instead of writing to whatever process.cwd() happens to be. This
+ * prevents a scratch/test session dir (no kits/ ancestor) from silently clobbering an
+ * unrelated real repo's delivery/trust.bundle when invoked with that repo as cwd (see
+ * evals/integration/test_checkpoint_signing.sh TEST 2 and the WS5 session findings at
+ * .kontourai/flow-agents/ws5-governance-kit-slice1 for the root cause this fixes).
  * Idempotent: overwrites on re-delivery.
  */
-export declare function publishDelivery(dir: string, repoRoot: string): Promise<void>;
+export declare function publishDelivery(dir: string, repoRoot: string | null): Promise<void>;
 export declare function validateLearningCorrection(record: AnyObj): void;
 export declare function normalizeLearning(raw: AnyObj, timestamp: string): AnyObj;
 /** Shape of a claim from the trust.bundle */
@@ -219,7 +226,7 @@ export interface TrustClaim {
     id: string;
     subjectType: string;
     subjectId: string;
-    surface: string;
+    facet?: string;
     claimType: string;
     fieldOrBehavior: string;
     value: string;
@@ -236,7 +243,7 @@ export interface BundleFile {
     events: AnyObj[];
     policies: AnyObj[];
 }
-/** The gate block signal read from .flow-agents/.goal-fit-block-streak.json */
+/** The gate block signal read from .kontourai/flow-agents/.goal-fit-block-streak.json */
 export interface GateBlockSignal {
     /** True when the streak file exists AND count >= 1 */
     blocked: boolean;
@@ -251,13 +258,13 @@ export interface GateBlockSignal {
  */
 export type GateCalibration = "correct" | "false_block" | "missed_block";
 /**
- * Read the gate block signal from .flow-agents/.goal-fit-block-streak.json
+ * Read the gate block signal from .kontourai/flow-agents/.goal-fit-block-streak.json
  * (written by scripts/hooks/stop-goal-fit.js when block mode fires).
  * The file sits at <artifact-root>/.goal-fit-block-streak.json — one level
  * above the session artifact dir. Fail-open: returns { blocked: false } when
  * the file is absent or unreadable.
  *
- * @param artifactRoot  The .flow-agents root dir (parent of session slug dir).
+ * @param artifactRoot  The runtime artifact root dir (parent of session slug dir).
  */
 export declare function readGateBlockSignal(artifactRoot: string): GateBlockSignal;
 /**