@kontourai/flow-agents 3.7.0 → 3.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [3.8.0](https://github.com/kontourai/flow-agents/compare/v3.7.0...v3.8.0) (2026-07-12)
+
+
+### Features
+
+* **packaging:** install portable skills under .agents ([#551](https://github.com/kontourai/flow-agents/issues/551)) ([12f12e3](https://github.com/kontourai/flow-agents/commit/12f12e3d0a32b398e47a9ac01604179c58bf14ba))
+
+
+### Fixes
+
+* **builder:** make gate evidence sync visit-safe ([#558](https://github.com/kontourai/flow-agents/issues/558)) ([1c0e8dc](https://github.com/kontourai/flow-agents/commit/1c0e8dcea6bdfd7d54484f950b2432fcf727b0ea))
+
 ## [3.7.0](https://github.com/kontourai/flow-agents/compare/v3.6.0...v3.7.0) (2026-07-12)
 
 

package/build/src/builder-flow-runtime.js

@@ -277,9 +277,13 @@ async function syncAndProject(context, initial, sidecarSnapshot) {
         const snapshot = stageTrustBundleSnapshot(context);
         try {
             const rawBundle = JSON.parse(snapshot.raw.toString("utf8"));
-            const gateEvidence = await bundleGateEvidence(rawBundle, gates[0], run.state.subject, context.projectRoot);
+            const gateEvidence = await bundleGateEvidence(rawBundle, gates[0], run.state, run.state.subject, context.projectRoot, manifestEvidence(run.manifest));
             if (gateEvidence) {
-                const alreadyAttached = manifestEvidence(run.manifest).some((entry) => entry.gate_id === gates[0].id && entry.sha256 === snapshot.sha256);
+                const alreadyAttached = manifestEvidence(run.manifest).some((entry) => entry.gate_id === gates[0].id
+                    && entry.sha256 === snapshot.sha256
+                    && typeof entry.superseded_by !== "string"
+                    && timestampAtOrAfter(entry.attached_at, gateEvidence.visitEnteredAt)
+                    && gateEvidence.expectationIds.every((expectationId) => Array.isArray(entry.expectation_ids) && entry.expectation_ids.includes(expectationId)));
                 if (!alreadyAttached) {
                     const supersede = manifestEvidence(run.manifest)
                         .filter((entry) => entry.gate_id === gates[0].id && typeof entry.superseded_by !== "string")
@@ -294,6 +298,7 @@ async function syncAndProject(context, initial, sidecarSnapshot) {
                             ...(supersede.length > 0 ? { supersede } : {}),
                             ...(gateEvidence.failed ? { status: "failed" } : {}),
                             ...(gateEvidence.routeReason ? { routeReason: gateEvidence.routeReason } : {}),
+                            expectationIds: gateEvidence.expectationIds,
                         },
                     });
                     attached = true;
@@ -377,15 +382,67 @@ function persistedFlowId(state) {
 function openGatesForResult(run) {
     return openGates(JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8")), run.state);
 }
-async function bundleGateEvidence(bundle, gate, subject, projectRoot) {
+async function bundleGateEvidence(bundle, gate, state, subject, projectRoot, manifest) {
     if (!isRecord(bundle) || !Array.isArray(bundle.claims))
         return null;
-    const selectors = expectationsForGate(gate).map((expectation) => expectation.bundle_claim);
+    const expectations = expectationsForGate(gate);
+    const visit = currentGateVisit(state, String(gate.step));
+    const enteredAt = visit.enteredAt;
+    const synchronizedAt = Date.now();
+    const maxClockSkewMs = 30_000;
+    const priorVisitClaimIds = new Set();
+    const priorVisitEvidenceIds = new Set();
+    for (const entry of manifest) {
+        if (entry.gate_id !== String(gate.id))
+            continue;
+        const claims = isRecord(entry.bundle) && Array.isArray(entry.bundle.claims) ? entry.bundle.claims : [];
+        for (const historical of claims) {
+            if (isRecord(historical) && typeof historical.id === "string")
+                priorVisitClaimIds.add(historical.id);
+        }
+        const evidence = isRecord(entry.bundle) && Array.isArray(entry.bundle.evidence) ? entry.bundle.evidence : [];
+        for (const historical of evidence) {
+            if (isRecord(historical) && typeof historical.id === "string")
+                priorVisitEvidenceIds.add(historical.id);
+        }
+    }
+    const claimIsCurrent = (claim) => {
+        if (typeof claim.id !== "string" || priorVisitClaimIds.has(claim.id))
+            return false;
+        const timestamps = [];
+        const createdAt = parseTimestamp(claim.createdAt);
+        if (createdAt !== null)
+            timestamps.push(createdAt);
+        if (Array.isArray(bundle.evidence))
+            for (const evidence of bundle.evidence) {
+                if (!isRecord(evidence) || evidence.claimId !== claim.id)
+                    continue;
+                if (typeof evidence.id !== "string" || priorVisitEvidenceIds.has(evidence.id))
+                    return false;
+                const observedAt = parseTimestamp(evidence.observedAt);
+                if (observedAt !== null)
+                    timestamps.push(observedAt);
+            }
+        const initialAcquisitionSkew = visit.initial && claim.claimType === "builder.pull-work.selected" ? maxClockSkewMs : 0;
+        return timestamps.some((timestamp) => timestamp >= enteredAt - initialAcquisitionSkew
+            && timestamp <= synchronizedAt + maxClockSkewMs);
+    };
     const relevant = bundle.claims.filter((claim) => {
         if (!isRecord(claim))
             return false;
-        return selectors.some((candidate) => candidate.claimType === claim.claimType
-            && (!candidate.subjectType || candidate.subjectType === claim.subjectType));
+        if (claim.producerStatus === "superseded")
+            return false;
+        const metadata = isRecord(claim.metadata) ? claim.metadata : null;
+        if (metadata && typeof metadata.superseded_by === "string")
+            return false;
+        return expectations.some((expectation) => {
+            const candidate = expectation.bundle_claim;
+            return candidate
+                && claimIsCurrent(claim)
+                &&
+                    candidate.claimType === claim.claimType
+                && (!candidate.subjectType || candidate.subjectType === claim.subjectType);
+        });
     });
     if (relevant.length === 0)
         return null;
@@ -393,6 +450,11 @@ async function bundleGateEvidence(bundle, gate, subject, projectRoot) {
         throw new BuilderBuildRunInputError("evidence.claims.metadata.workflow_subject_ref", "must match the persisted run subject");
     }
     const failed = relevant.some((claim) => claim.value === "fail" || claim.status === "disputed");
+    const expectationIds = expectations.filter((expectation) => relevant.some((claim) => {
+        const selector = expectation.bundle_claim;
+        return selector.claimType === claim.claimType && (!selector.subjectType || selector.subjectType === claim.subjectType);
+    })).map((expectation) => expectation.id);
+    const missingRequired = expectations.filter((expectation) => expectation.required && !expectationIds.includes(expectation.id));
     const routeReasons = [...new Set(relevant.flatMap((claim) => {
             const metadata = isRecord(claim.metadata) ? claim.metadata : null;
             const gateClaim = metadata && isRecord(metadata.gate_claim) ? metadata.gate_claim : null;
@@ -402,6 +464,13 @@ async function bundleGateEvidence(bundle, gate, subject, projectRoot) {
         throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", "must agree across current-gate claims");
     }
     const routeReason = routeReasons[0] ?? null;
+    if (failed && !routeReason)
+        return null;
+    // Passing evidence waits for the complete expectation set. A failing
+    // snapshot is complete only when a gate producer explicitly declares its
+    // route reason; report-only disputed critique state remains pending.
+    if (!failed && missingRequired.length > 0)
+        return null;
     if (routeReason && !failed) {
         throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", "requires failed current-gate evidence");
     }
@@ -412,7 +481,33 @@ async function bundleGateEvidence(bundle, gate, subject, projectRoot) {
     if (String(gate.id) === "verify-gate" && relevant.some((claim) => claim.claimType === "builder.verify.tests" && claim.value === "pass")) {
         await assertVerifiedTestsTrust(bundle.claims, projectRoot);
     }
-    return { failed, routeReason };
+    return { failed, routeReason, expectationIds, visitEnteredAt: enteredAt };
+}
+function currentGateVisit(state, step) {
+    let enteredAt = null;
+    for (const transition of state.transitions ?? []) {
+        if (transition.to_step !== step)
+            continue;
+        const parsed = parseTimestamp(transition.at);
+        if (parsed !== null)
+            enteredAt = parsed;
+    }
+    const initial = parseTimestamp(state.updated_at);
+    if (enteredAt !== null)
+        return { enteredAt, initial: false };
+    if (initial !== null)
+        return { enteredAt: initial, initial: true };
+    throw new BuilderBuildRunInputError("flow_run.state.updated_at", "must establish the current gate visit boundary");
+}
+function parseTimestamp(value) {
+    if (typeof value !== "string")
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function timestampAtOrAfter(value, boundary) {
+    const parsed = parseTimestamp(value);
+    return parsed !== null && parsed >= boundary;
 }
 async function assertVerifiedTestsTrust(claims, projectRoot) {
     const testClaims = claims.filter((claim) => isRecord(claim)

package/build/src/cli/assignment-provider.js

@@ -626,7 +626,19 @@ export function performLocalReleaseUnderLock(artifactRoot, subjectId, releasedBy
         // seam, relocated to this write path).
         const holderActorKey = existing.actor_key || helper.serializeActor(existing.actor);
         const releasedByActorKey = opts.actorKey || helper.serializeActor(releasedBy);
-        if (holderActorKey !== releasedByActorKey) {
+        // Pre-3.7 lifecycle events could persist the derived ancestry actor before
+        // sanitizeSegment removed ':' separators. Modern explicit/env release paths
+        // always use the sanitized form. Accept only that one-way legacy migration;
+        // never normalize two modern keys or relax ownership to a prefix match.
+        const sameActorStruct = existing.actor.runtime === releasedBy.runtime
+            && existing.actor.session_id === releasedBy.session_id
+            && existing.actor.host === releasedBy.host
+            && (existing.actor.human ?? null) === (releasedBy.human ?? null);
+        const legacyActorKeyMatches = holderActorKey.includes(":")
+            && holderActorKey === helper.serializeActor(existing.actor)
+            && helper.sanitizeSegment(holderActorKey) === releasedByActorKey
+            && sameActorStruct;
+        if (holderActorKey !== releasedByActorKey && !legacyActorKeyMatches) {
             if (tolerateNoActiveClaim)
                 return null;
             throw new Error(`--actor-json does not match the current holder (${holderActorKey}); refusing to release a claim held by someone else`);

package/build/src/cli/workflow-sidecar.js

@@ -880,7 +880,9 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             continue;
         const subjectId = `${slug}/${check.id}`;
         const fieldOrBehavior = String(check.summary ?? check.id);
-        const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
+        const gateClaimIdentityVersion = check._gate_claim_identity_version === 2 ? 2 : 1;
+        const gateClaimRecordedAt = gateClaimIdentityVersion === 2 && typeof check._gate_claim_recorded_at === "string" ? check._gate_claim_recorded_at : null;
+        const claimId = generateClaimId(subjectId, "flow-agents.workflow", gateClaimRecordedAt ? `${fieldOrBehavior}::gate-visit::${gateClaimRecordedAt}` : fieldOrBehavior);
         const evId = `ev:${claimId}`;
         const legacyClaimType = `workflow.check.${check.kind ?? "external"}`;
         const cmd = typeof check.command === "string" ? check.command.replace(/\s+/g, " ").trim() : "";
@@ -1034,7 +1036,7 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             // restored stamp) takes the currently-active step's id.
             const declaredStepId = gateClaimDeclaredStepId ?? (activeStep ? activeStep.stepId : null);
             const declaredMetadata = gateClaimExpectationId
-                ? { ...claimMetadata, gate_claim: { expectation_id: gateClaimExpectationId, claim_type: declared.claimType, subject_type: declared.subjectType, step_id: declaredStepId, ...(gateClaimRouteReason ? { route_reason: gateClaimRouteReason } : {}) } }
+                ? { ...claimMetadata, gate_claim: { expectation_id: gateClaimExpectationId, claim_type: declared.claimType, subject_type: declared.subjectType, step_id: declaredStepId, ...(gateClaimIdentityVersion === 2 ? { identity_version: 2 } : {}), ...(gateClaimRecordedAt ? { recorded_at: gateClaimRecordedAt } : {}), ...(gateClaimRouteReason ? { route_reason: gateClaimRouteReason } : {}) } }
                 : claimMetadata;
             const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: effectiveStatus, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, ...(declaredMetadata ? { metadata: declaredMetadata } : {}) };
             const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [evItem], events: claimEvents, policies: [declaredPolicy] });
@@ -1053,7 +1055,9 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             continue;
         const subjectId = `${slug}/${criterion.id}`;
         const fieldOrBehavior = String(criterion.description ?? criterion.id);
-        const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
+        const criterionIdentityVersion = criterion.identity_version === 2 ? 2 : 1;
+        const criterionVerifiedAt = criterionIdentityVersion === 2 && typeof criterion.verified_at === "string" ? criterion.verified_at : null;
+        const claimId = generateClaimId(subjectId, "flow-agents.workflow", criterionVerifiedAt ? `${fieldOrBehavior}::verified::${criterionVerifiedAt}` : fieldOrBehavior);
         const legacyClaimType = "workflow.acceptance.criterion";
         const policy = ensurePolicy(legacyClaimType, "high", []);
         const evStatus = criterionStatusToEventStatus(String(criterion.status ?? ""));
@@ -1068,7 +1072,7 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         if (declared) {
             // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
             const declaredPolicy = ensurePolicy(declared.claimType, "high", []);
-            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, metadata: { origin: "acceptance", criterion: { id: criterion.id, description: criterion.description ?? criterion.id, status: criterion.status, evidence_refs: Array.isArray(criterion.evidence_refs) ? criterion.evidence_refs : [] }, ...(workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}) } };
+            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: declaredPolicy.id, metadata: { origin: "acceptance", criterion: { id: criterion.id, description: criterion.description ?? criterion.id, status: criterion.status, evidence_refs: Array.isArray(criterion.evidence_refs) ? criterion.evidence_refs : [], ...(criterionIdentityVersion === 2 ? { identity_version: 2 } : {}), ...(criterionVerifiedAt ? { verified_at: criterionVerifiedAt } : {}) }, ...(workflowSubjectRef ? { workflow_subject_ref: workflowSubjectRef } : {}) } };
             const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [], events: claimEvents, policies: [declaredPolicy] });
             claims.push({ ...declaredClaimObj, status: declaredStatus });
         }
@@ -1092,10 +1096,12 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         const supersededBy = typeof c.superseded_by === "string" && c.superseded_by.length > 0 ? c.superseded_by : null;
         const critiqueReviewer = String(c.reviewer ?? "tool-code-reviewer");
         const critiqueReviewedAt = String(c.reviewed_at ?? ts);
+        const critiqueIdentityVersion = c.identity_version === 2 ? 2 : 1;
         const critMeta = {
             origin: "critique",
             reviewer: critiqueReviewer,
             reviewed_at: critiqueReviewedAt,
+            ...(critiqueIdentityVersion === 2 ? { identity_version: 2 } : {}),
             findings: Array.isArray(c.findings) ? c.findings : [],
             lanes: Array.isArray(c.lanes) ? c.lanes : [],
             review_target: c.review_target && typeof c.review_target === "object" ? c.review_target : { artifacts: [] },
@@ -1107,7 +1113,9 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         // A superseded historical write gets a distinct, stable claimId so it co-exists with the live
         // claim of the same critique id (never overwrites or duplicates it). The salt is reproducible
         // across rebuilds because superseded_by + reviewed_at are preserved in metadata.
-        const claimIdSalt = supersededBy ? `${fieldOrBehavior}::superseded::${supersededBy}::${critiqueReviewedAt}` : fieldOrBehavior;
+        const claimIdSalt = critiqueIdentityVersion === 2
+            ? `${fieldOrBehavior}::reviewed::${critiqueReviewedAt}${supersededBy ? `::superseded::${supersededBy}` : ""}`
+            : (supersededBy ? `${fieldOrBehavior}::superseded::${supersededBy}::${critiqueReviewedAt}` : fieldOrBehavior);
         const claimId = generateClaimId(subjectId, "flow-agents.workflow", claimIdSalt);
         const legacyClaimType = "workflow.critique.review";
         const policy = ensurePolicy(legacyClaimType, "medium", []);
@@ -2770,7 +2778,7 @@ function requireObservedCommandRefs(refs, observedCommands, label, requireAll =
             die(`${label} requires a top-level command evidence ref for every successful observed command`);
     }
 }
-function completePassingCriteria(existing, raw, observedCommands) {
+function completePassingCriteria(existing, raw, observedCommands, verifiedAt) {
     if (raw.length === 0)
         die("record-gate-claim requires --criterion-json for a passing tests-evidence claim");
     const incoming = raw.map((value) => parseJson(value, "--criterion-json"));
@@ -2794,7 +2802,7 @@ function completePassingCriteria(existing, raw, observedCommands) {
         if (refs.length === 0)
             die(`criterion ${ids[index]} requires reviewable evidence_refs`);
         requireObservedCommandRefs(refs, observedCommands, `criterion ${ids[index]}`);
-        return { ...expectedById.get(ids[index]), status: "pass", evidence_refs: refs };
+        return { ...expectedById.get(ids[index]), status: "pass", evidence_refs: refs, identity_version: 2, verified_at: verifiedAt };
     });
 }
 const critiqueStatuses = new Set(["pass", "fail", "not_verified"]);
@@ -3234,6 +3242,10 @@ function checksFromBundle(dir) {
             check._gate_claim_declared_subject = gc.subject_type;
         if (typeof gc.step_id === "string")
             check._gate_claim_declared_step_id = gc.step_id;
+        if (typeof gc.recorded_at === "string")
+            check._gate_claim_recorded_at = gc.recorded_at;
+        if (gc.identity_version === 2)
+            check._gate_claim_identity_version = 2;
         if (typeof gc.route_reason === "string")
             check._gate_claim_route_reason = gc.route_reason;
     };
@@ -3423,6 +3435,7 @@ function critiquesFromBundle(dir) {
             review_target: md.review_target && typeof md.review_target === "object" && !Array.isArray(md.review_target) ? md.review_target : { artifacts: [] },
             reviewer: typeof md.reviewer === "string" ? md.reviewer : "tool-code-reviewer",
             reviewed_at: typeof md.reviewed_at === "string" ? md.reviewed_at : (c.updatedAt || c.createdAt || now()),
+            ...(md.identity_version === 2 ? { identity_version: 2 } : {}),
             artifact_refs: Array.isArray(md.artifact_refs) ? md.artifact_refs : [],
             ...(typeof md.superseded_by === "string" && md.superseded_by.length > 0 ? { superseded_by: md.superseded_by } : {}),
         };
@@ -3444,6 +3457,8 @@ function criteriaFromBundle(dir) {
             description: typeof saved.description === "string" ? saved.description : (claim.fieldOrBehavior || ""),
             status: typeof saved.status === "string" ? saved.status : (claim.value ?? "not_verified"),
             evidence_refs: Array.isArray(saved.evidence_refs) ? saved.evidence_refs : [],
+            ...(typeof saved.verified_at === "string" ? { verified_at: saved.verified_at } : {}),
+            ...(saved.identity_version === 2 ? { identity_version: 2 } : {}),
         };
     })
         .filter((criterion) => typeof criterion.id === "string" && criterion.id.length > 0);
@@ -3503,7 +3518,7 @@ async function recordEvidence(p) {
         die("record-evidence requires at least one --check-json or --surface-trust-json");
     validateAcceptanceEvidenceRefs(dir, p);
     // Phase 4c: bundle is the sole verification artifact — stop writing evidence.json and acceptance.json update.
-    const ts = opt(p, "timestamp", now());
+    const ts = opt(p, "timestamp", new Date().toISOString());
     // #298: readBundleState + merge-by-id instead of unconditionally replacing every prior check —
     // record-evidence previously never called checksFromBundle(dir), so it dropped every check
     // recorded by an earlier record-evidence/record-check/record-gate-claim call. A later check
@@ -3710,7 +3725,7 @@ function diagnostic(dir, code, summary) {
 async function recordGateClaim(p) {
     const dir = artifactDirFrom(p.positional[0] || die("artifact directory is required"));
     const slug = taskSlugFor(dir, opt(p, "task-slug"));
-    const ts = opt(p, "timestamp", now());
+    const ts = opt(p, "timestamp", new Date().toISOString());
     const statusVal = opt(p, "status");
     if (!["pass", "fail", "not_verified"].includes(statusVal))
         die("--status must be one of: pass, fail, not_verified");
@@ -3795,6 +3810,8 @@ async function recordGateClaim(p) {
         status: statusVal,
         summary,
         _gate_claim_expectation_id: targetExpectation.id,
+        _gate_claim_identity_version: 2,
+        _gate_claim_recorded_at: ts,
         ...(routeReason ? { _gate_claim_route_reason: routeReason } : {}),
     };
     // Include structured evidence refs if provided
@@ -3836,7 +3853,7 @@ async function recordGateClaim(p) {
     // SAME expectation id supersedes the earlier check for that expectation (mergeChecksById); a
     // gate claim against a different expectation is additive.
     const _existingState = readBundleState(dir);
-    const criteria = mustRunTests ? completePassingCriteria(_existingState.criteria, opts(p, "criterion-json"), observedCommandNames) : _existingState.criteria;
+    const criteria = mustRunTests ? completePassingCriteria(_existingState.criteria, opts(p, "criterion-json"), observedCommandNames, ts) : _existingState.criteria;
     if (mustRunTests) {
         const liveCritiques = _existingState.critiques.filter((critique) => !critique.superseded_by);
         if (liveCritiques.length === 0 || liveCritiques.some((critique) => !critiqueIsCleanAndCurrent(dir, critique))) {
@@ -4062,7 +4079,8 @@ async function recordCritique(p) {
     const critique = {
         id: critiqueId,
         reviewer: opt(p, "reviewer", "tool-code-reviewer"),
-        reviewed_at: opt(p, "timestamp", now()),
+        reviewed_at: opt(p, "timestamp", new Date().toISOString()),
+        identity_version: 2,
         verdict,
         summary,
         lanes,

package/build/src/cli/workflow.js

@@ -200,7 +200,7 @@ async function evidence(sessionDir, argv, json) {
         // session state cannot change mid-invocation.
         const caller = assertMatchingAssignmentActor(sessionDir, slug);
         const repaired = await recoverBuilderFlowSession({ sessionDir });
-        const beforeEvidence = manifestEvidenceDigests(repaired.run.manifest);
+        const beforeEvidence = manifestEvidenceIdentity(repaired.run.manifest);
         await mainFromPublicWorkflow([
             "record-gate-claim",
             sessionDir,
@@ -208,27 +208,34 @@ async function evidence(sessionDir, argv, json) {
             "--actor",
             caller.actorKey,
         ]);
-        await syncBuilderFlowSession({ sessionDir });
+        const synchronized = await syncBuilderFlowSession({ sessionDir });
         const digest = fileSha256(path.join(sessionDir, "trust.bundle"));
         const run = await loadBuilderFlowRun({ cwd: repaired.projectRoot, runId: slug });
-        const afterEvidence = manifestEvidenceDigests(run.manifest);
-        const newEvidence = afterEvidence.filter((value) => !beforeEvidence.includes(value));
-        if (newEvidence.length !== 1 || newEvidence[0] !== digest) {
+        const afterEvidence = manifestEvidenceIdentity(run.manifest);
+        const beforeIds = new Set(beforeEvidence.map((entry) => entry.id));
+        const newEvidence = afterEvidence.filter((entry) => !beforeIds.has(entry.id));
+        if (synchronized.attached && (newEvidence.length !== 1 || newEvidence[0]?.sha256 !== digest)) {
             throw new Error("workflow evidence did not attach exactly this invocation's resulting trust.bundle digest");
         }
+        if (!synchronized.attached && newEvidence.length !== 0) {
+            throw new Error("workflow evidence changed the canonical manifest while synchronization reported no attachment");
+        }
         const updatedSidecar = readBoundSession(sessionDir).sidecar;
         return immutableReport({
             run_id: run.runId,
             status: run.state.status,
             current_step: run.state.current_step,
-            attached: true,
+            attached: synchronized.attached,
+            awaiting_evidence: !synchronized.attached,
             next_action: updatedSidecar.next_action ?? null,
         });
     });
     if (json)
         console.log(JSON.stringify(report));
     else
-        console.log(`Recorded evidence; canonical run is ${report.status} at ${report.current_step}.`);
+        console.log(report.attached
+            ? `Recorded evidence; canonical run is ${report.status} at ${report.current_step}.`
+            : `Recorded evidence; canonical run is awaiting the remaining gate expectations at ${report.current_step}.`);
     return 0;
 }
 async function critique(sessionDir, argv, json) {
@@ -541,11 +548,14 @@ function immutableReport(value) {
         immutableReport(nested);
     return Object.freeze(value);
 }
-function manifestEvidenceDigests(manifest) {
+function manifestEvidenceIdentity(manifest) {
     const evidence = Array.isArray(manifest.evidence) ? manifest.evidence : [];
     return evidence
-        .map((entry) => entry && typeof entry === "object" ? entry.sha256 : null)
-        .filter((digest) => typeof digest === "string");
+        .flatMap((entry) => entry && typeof entry === "object"
+        && typeof entry.id === "string"
+        && typeof entry.sha256 === "string"
+        ? [{ id: String(entry.id), sha256: String(entry.sha256) }]
+        : []);
 }
 function optionalFileDigest(file) {
     try {

package/build/src/tools/build-universal-bundles.js

@@ -137,6 +137,55 @@ function copyTree(src, dest, target, rootReplacement) {
         }
     }
 }
+const skillResourcePattern = /(?:^|[`("'\s])(context\/contracts\/[A-Za-z0-9._/-]+\.md)(?=$|[`),"'\s])/gm;
+/** Export a skill as a self-contained package. Shared instruction resources
+ * retain the relative paths used by SKILL.md so runtime resolution is local. */
+function exportSkillPackage(src, dest, target) {
+    const sourceDir = path.dirname(src);
+    copyTree(sourceDir, dest, target, "<bundle-root>");
+    const skillText = readText(src);
+    const resources = new Set();
+    for (const match of skillText.matchAll(skillResourcePattern))
+        resources.add(match[1]);
+    for (const rel of [...resources].sort()) {
+        if (path.isAbsolute(rel) || rel.split("/").includes("..")) {
+            throw new Error(`skill '${path.basename(sourceDir)}': unsafe local resource '${rel}'`);
+        }
+        const source = path.resolve(root, rel);
+        const output = path.resolve(dest, rel);
+        if (!source.startsWith(`${path.resolve(root)}${path.sep}`) || !output.startsWith(`${path.resolve(dest)}${path.sep}`)) {
+            throw new Error(`skill '${path.basename(sourceDir)}': local resource escapes package '${rel}'`);
+        }
+        if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
+            throw new Error(`skill '${path.basename(sourceDir)}': missing local resource '${rel}'`);
+        }
+        if (fs.existsSync(output)) {
+            const existing = fs.readFileSync(output);
+            const incoming = fs.readFileSync(source);
+            if (!existing.equals(incoming))
+                throw new Error(`skill '${path.basename(sourceDir)}': resource collision '${rel}'`);
+            continue;
+        }
+        writeText(output, sanitizeText(readText(source), target, "<bundle-root>"));
+    }
+}
+function validateExportedSkillPackages(skillsRoot) {
+    if (!fs.existsSync(skillsRoot))
+        return;
+    for (const skillName of fs.readdirSync(skillsRoot).sort()) {
+        const skillDir = path.join(skillsRoot, skillName);
+        const skillFile = path.join(skillDir, "SKILL.md");
+        if (!fs.existsSync(skillFile))
+            continue;
+        for (const match of readText(skillFile).matchAll(skillResourcePattern)) {
+            const rel = match[1];
+            const resolved = path.resolve(skillDir, rel);
+            if (!resolved.startsWith(`${path.resolve(skillDir)}${path.sep}`) || !fs.existsSync(resolved)) {
+                throw new Error(`skill '${skillName}': unresolved exported resource '${rel}'`);
+            }
+        }
+    }
+}
 function resolveSourcePath(pathText) {
     let normalized = pathText;
     for (const alias of manifest.source_root_aliases)
@@ -473,9 +522,10 @@ function buildCodex(agents) {
     writeText(path.join(bundle, ".codex/hooks.json"), exportCodexHooks());
     for (const spec of targetAgents)
         writeText(path.join(bundle, ".codex/agents", `${spec.name}.toml`), exportCodexAgent(spec));
-    for (const { name, src } of collectAllSkills()) {
-        writeText(path.join(bundle, ".codex/skills", name, "SKILL.md"), sanitizeText(readText(src), "codex", "<bundle-root>"));
-    }
+    const skillsRoot = path.join(bundle, ".agents/skills");
+    for (const { name, src } of collectAllSkills())
+        exportSkillPackage(src, path.join(skillsRoot, name), "codex");
+    validateExportedSkillPackages(skillsRoot);
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Codex", targetAgents, manifest.codex.task_dir));
     writeText(path.join(bundle, "README.md"), exportTargetReadme("Codex", "bash install.sh /path/to/workspace", CODEX_LIVE_HOOKS_README));
     writeText(path.join(bundle, "install.sh"), installScript("Codex", "/path/to/workspace", undefined, undefined, { configRelPath: ".codex/hooks.json", managedConfigRelPath: ".codex/hooks.json", runtime: "codex", version: pkgVersion }));

package/docs/getting-started.md

@@ -30,7 +30,15 @@ For a normal Codex global install, target the Codex home instead of a project wo
 npx @kontourai/flow-agents init --runtime codex --global --activate-kits --yes
 ```
 
-That installs into `CODEX_HOME` when it is set, otherwise `~/.codex`. Use `--dest /path/to/codex-home` only when you need an explicit override for an isolated install, CI fixture, or test.
+That splits installation by ownership: Codex-only runtime assets go into `CODEX_HOME` when set (otherwise `~/.codex`), while portable skills go into Codex's documented user catalog at `$HOME/.agents/skills`. A repository bundle install similarly exposes skills at `<repo>/.agents/skills`.
+
+Pass a positional runtime destination and `--skills-dir PATH` when both roots must be isolated, or set `FLOW_AGENTS_SKILLS_DIR` for headless environments:
+
+```bash
+bash scripts/install-codex-home.sh /tmp/codex-home --skills-dir /tmp/agents/skills
+```
+
+Installer output reports both destinations. Reinstall preserves unknown user skills and migrates only unchanged Flow Agents-owned files from the former `CODEX_HOME/skills` layout; modified legacy content is retained. Flow Agents intentionally does not create a compatibility symlink because the Codex runtime home must not own or mask a universal user catalog, and the installer refuses to write through symlinked destinations.
 
 Keep generated Codex base config lean. Put profile-specific model, provider, and approval settings in separate `<profile>.config.toml` files and select them with `codex --profile <name>`.
 

package/docs/spec/builder-flow-runtime.md

@@ -63,8 +63,36 @@ does not create a Flow run.
 
 After a gate producer writes `trust.bundle`, the public evidence path
 synchronizes the existing run while holding the assignment subject lock.
-Synchronization is digest-idempotent: the same trust bundle is not attached
-twice.
+Synchronization selects only live claims: producer-superseded claims and claims
+carrying `metadata.superseded_by` remain auditable history but never determine
+the current outcome. Passing evidence is published atomically only when every
+required expectation for the gate is present; this prevents sequential critique
+writes from attaching an intermediate partial snapshot and consuming a
+route-back attempt. Failed evidence may still synchronize immediately when it
+carries a route reason declared by the gate; a disputed report-only critique is
+not itself a routed gate decision and remains pending.
+
+Attachments carry the exact expectation ids selected from the current bundle.
+Digest idempotence applies only while an unsuperseded attachment for that gate
+and expectation set remains live. After route-back, claims must be current for
+the new gate visit before synchronization, and claim/evidence identities used
+by any earlier attachment to that gate can never satisfy the later visit.
+Gate claims, verified criteria, and critiques carry producer-recorded version
+timestamps plus `identity_version: 2` in their identity derivation so legitimate
+re-verification creates new identities. Unmarked pre-upgrade records retain the
+legacy identity formula during rebuild; installing new code alone can never
+manufacture a fresh identity. Because those identities are embedded in TrustBundle bytes, a
+genuinely new identity necessarily changes the bundle SHA-256; byte-identical
+replay remains pending rather than consuming another attempt.
+
+Every gate visit has a canonical boundary: the latest Flow transition into the
+step, or the run's initial timestamp for its entry step. Claim creation and
+observation timestamps must fall within that visit and may not be more than 30
+seconds ahead of synchronization. The sole pre-boundary allowance is the
+30-second acquisition window for the assignment-backed `selected-work` claim,
+which is intentionally produced immediately before the canonical run starts.
+Previously attached claim and evidence identities are excluded from every later
+visit to the same gate regardless of timestamp skew.
 
 ## Public Status And Recovery
 
@@ -119,6 +147,12 @@ Workflow steering surfaces these fields on session start and prompt submission.
 Stop hook treats an unfinished canonical Flow run as active even during pickup or
 planning, blocks a premature stop in block mode, and does not release its liveness
 claim. A run is complete only when Flow reaches its terminal step.
+
+Projection is always derived from the canonical run's `current_step`, including
+composed steps that have no legacy sidecar phase (`merge-ready-ci` and `learn`).
+Both the legacy `current.json` pointer and every matching per-actor pointer are
+updated from that canonical step; `phase_map` is presentation metadata, not the
+authority for pointer navigation.
 # Builder Lifecycle Authority
 
 The canonical Flow run owns pause, resume, and cancellation. The current assignment actor may

package/evals/integration/test_builder_step_producers.sh

@@ -456,6 +456,9 @@ record_public_expectation() {
     *) _fail "public producer fixture has no durable artifact for $expectation"; return ;;
   esac
   local -a args=(evidence --session-dir "$PUBLIC_SESSION" --expectation "$expectation" --status "$status" --summary "public producer fixture records a reviewable durable artifact" --evidence-ref-json "{\"kind\":\"artifact\",\"file\":\"$artifact\",\"summary\":\"Fixture artifact for $expectation.\"}")
+  if [ "$expectation" = "tests-evidence" ] && [ "$status" = "fail" ]; then
+    args+=(--route-reason implementation_defect)
+  fi
   if [ "$expectation" = "tests-evidence" ] && [ "$status" = "pass" ]; then
     local test_command criterion_one criterion_two command_ref
     test_command="bash checks/check-public-session.sh .kontourai/flow-agents/$slug/state.json"
@@ -614,16 +617,46 @@ ROUTE_CRITIQUE_OUTPUT="$(public_review critique --session-dir "$PUBLIC_SESSION"
   --artifact-ref "$PUBLIC_SESSION/$(basename "$PUBLIC_SESSION")--deliver.md" \
   --lane-json "{\"id\":\"code-review\",\"status\":\"pass\",\"summary\":\"Public fixture code review completed.\",\"evidence_refs\":[{\"kind\":\"artifact\",\"file\":\"$PUBLIC_SESSION/$(basename "$PUBLIC_SESSION")--deliver.md\",\"summary\":\"Reviewed public fixture delivery artifact.\"}]}" 2>&1)" \
   || _fail "public authenticated critique failed before failed tests-evidence: $ROUTE_CRITIQUE_OUTPUT"
+# Seed current verified acceptance prerequisites through the private producer
+# without synchronizing Flow. The subsequent public failed tests claim replaces
+# the provisional passing tests check, preserves these criteria + the clean
+# critique, and is the only attachment/evaluation for this gate visit.
+ROUTE_TEST_COMMAND="bash checks/check-public-session.sh .kontourai/flow-agents/$(basename "$PUBLIC_SESSION")/state.json"
+ROUTE_COMMAND_REF="$(node - "$ROUTE_TEST_COMMAND" <<'NODE'
+const command = process.argv[2];
+process.stdout.write(JSON.stringify({ kind: 'command', excerpt: command, summary: 'Current route-back prerequisite command.' }));
+NODE
+)"
+ROUTE_CRITERION_ONE="$(node - "$ROUTE_TEST_COMMAND" <<'NODE'
+const command = process.argv[2];
+process.stdout.write(JSON.stringify({ id: 'AC-1', status: 'pass', evidence_refs: [{ kind: 'command', excerpt: command, summary: 'Current AC-1 prerequisite.' }] }));
+NODE
+)"
+ROUTE_CRITERION_TWO="$(node - "$ROUTE_TEST_COMMAND" <<'NODE'
+const command = process.argv[2];
+process.stdout.write(JSON.stringify({ id: 'AC-2', status: 'pass', evidence_refs: [{ kind: 'command', excerpt: command, summary: 'Current AC-2 prerequisite.' }] }));
+NODE
+)"
+ROUTE_OBSERVED="$(node - "$ROUTE_TEST_COMMAND" <<'NODE'
+const command = process.argv[2];
+process.stdout.write(JSON.stringify({ command, exit_code: 0, test_count: 1, output_sha256: '0'.repeat(64) }));
+NODE
+)"
+CODEX_SESSION_ID=builder-public-producers flow_agents_node "workflow-sidecar" record-gate-claim "$PUBLIC_SESSION" \
+  --expectation tests-evidence --status pass --summary "Seed complete current acceptance prerequisites before routed failure." \
+  --command "$ROUTE_TEST_COMMAND" --observed-command-json "$ROUTE_OBSERVED" \
+  --evidence-ref-json "$ROUTE_COMMAND_REF" --criterion-json "$ROUTE_CRITERION_ONE" --criterion-json "$ROUTE_CRITERION_TWO" >/dev/null 2>&1 \
+  || _fail "failed to seed current acceptance prerequisites for routed failure"
 record_public_expectation "tests-evidence" "fail"
 ROUTE_REPORT="$(public_flow status --session-dir "$PUBLIC_SESSION" --json 2>/dev/null)"
 if node - "$ROUTE_REPORT" <<'NODE'
 const report = JSON.parse(process.argv[2]);
-if (report.current_step !== 'verify') process.exit(1);
-if ((report.next_action?.skills || []).join(',') !== 'review-work,verify-work') process.exit(2);
-if (!/attempt 1\/3 returned to `verify`/.test(report.next_action?.summary || '')) process.exit(3);
+if (report.current_step !== 'execute') process.exit(1);
+if ((report.next_action?.skills || []).join(',') !== 'execute-plan') process.exit(2);
+if (!/attempt 1\/3 returned to `execute` for `implementation_defect`/.test(report.next_action?.summary || '')) process.exit(3);
 NODE
 then
-  _pass "failed verify evidence routes back through Flow with attempt 1/3 and canonical producers"
+  _pass "complete failed verify evidence routes back through Flow once to execute for implementation_defect"
 else
   _fail "public failed-verify route-back was not projected correctly: $ROUTE_REPORT"
 fi