@kontourai/flow-agents 2.4.0 → 3.0.0

package/build/src/cli/effective-assignment-provider-settings.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): number;

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

@@ -0,0 +1,125 @@
+import * as child_process from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs, flagString, flagBool } from "../lib/args.js";
+import { readJson } from "../lib/fs.js";
+// Mirrors src/cli/effective-backlog-settings.ts's loadSettings/currentRepo/merge/findProject/
+// effective structure and its ask_user/configured result envelope exactly, pointed at the
+// AssignmentProvider settings schema/example instead of the backlog equivalents (#290 Wave 2
+// Task B). Deliberately NOT extracted into a shared helper with effective-backlog-settings.ts —
+// see the #290 plan artifact's Unresolved Questions #3 for the recorded rationale (duplicating
+// this file's small merge/repo-detection logic is lower-risk than refactoring a file outside
+// this issue's declared scope).
+const PROJECT_SETTINGS_RELATIVE_PATH = path.join("context", "settings", "assignment-provider-settings.json");
+function loadSettings(file) {
+    if (!fs.existsSync(file))
+        return null;
+    const data = readJson(file);
+    if (data.schema_version !== "1.0")
+        throw new Error(`${file}: unsupported schema_version ${String(data.schema_version)}`);
+    return data;
+}
+function repoFromText(text) {
+    const match = text.trim().match(/github\.com[:/]([^/]+)\/([^/.]+)(?:\.git)?$/);
+    return match ? { owner: match[1], name: match[2] } : null;
+}
+function currentRepo(repoPath) {
+    try {
+        const out = child_process.execFileSync("git", ["-C", repoPath, "remote", "get-url", "origin"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        const repo = repoFromText(out);
+        if (repo)
+            return repo;
+    }
+    catch { }
+    const packagePath = path.join(repoPath, "package.json");
+    if (fs.existsSync(packagePath)) {
+        const data = readJson(packagePath);
+        const repository = data.repository;
+        const url = typeof repository === "object" && repository !== null ? repository.url : repository;
+        if (typeof url === "string")
+            return repoFromText(url);
+    }
+    return null;
+}
+function merge(base, override) {
+    if (!base && !override)
+        return null;
+    if (!base)
+        return structuredClone(override);
+    if (!override)
+        return structuredClone(base);
+    const out = structuredClone(base);
+    for (const [key, value] of Object.entries(override)) {
+        out[key] = typeof value === "object" && value !== null && typeof out[key] === "object" && out[key] !== null && !Array.isArray(value)
+            ? merge(out[key], value)
+            : structuredClone(value);
+    }
+    return out;
+}
+function findProject(settings, repo) {
+    const projects = settings?.projects;
+    if (!Array.isArray(projects))
+        return null;
+    return projects.find((project) => {
+        const projectRepo = (project.project?.repo ?? {});
+        return projectRepo.owner === repo.owner && projectRepo.name === repo.name;
+    }) ?? null;
+}
+function defaultProjectSettingsPath() {
+    let cursor = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = path.join(cursor, PROJECT_SETTINGS_RELATIVE_PATH);
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return path.resolve(PROJECT_SETTINGS_RELATIVE_PATH);
+        cursor = parent;
+    }
+}
+function effective(repoPath, projectSettings, globalSettings) {
+    const repo = currentRepo(repoPath);
+    const projectDoc = loadSettings(projectSettings);
+    const globalDoc = loadSettings(globalSettings);
+    if (!repo)
+        return [{ status: "ask_user", reason: "could_not_identify_current_repo", message: "Ask the user which assignment AssignmentProvider to use for this workspace.", resolution: { project_settings_path: projectSettings, global_settings_path: globalSettings } }, 2];
+    const effectiveSettings = merge(merge(merge(globalDoc?.defaults, findProject(globalDoc, repo)), projectDoc?.defaults), findProject(projectDoc, repo));
+    if (!effectiveSettings)
+        return [{ status: "ask_user", reason: "no_assignment_provider_settings", message: "Ask the user which assignment AssignmentProvider to use before claiming work.", current_repo: repo, resolution: { project_settings_path: projectSettings, global_settings_path: globalSettings, checked: ["project", "global"] } }, 2];
+    return [{ status: "configured", current_repo: repo, source: findProject(projectDoc, repo) || projectDoc?.defaults ? "project" : "global", precedence: ["project.projects match", "project.defaults", "global.projects match", "global.defaults"], settings: effectiveSettings }, 0];
+}
+export function main(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+    try {
+        const [result, code] = effective(path.resolve(flagString(args.flags, "repo-path", ".") ?? "."), path.resolve(flagString(args.flags, "project-settings", defaultProjectSettingsPath()) ?? ""), path.resolve(flagString(args.flags, "global-settings", path.join(os.homedir(), ".config", "flow-agents", "assignment-provider-settings.json")) ?? ""));
+        if (flagBool(args.flags, "json"))
+            console.log(JSON.stringify(result, null, 2));
+        else
+            console.log(`status: ${String(result.status)}`);
+        return code;
+    }
+    catch (error) {
+        console.error(`error: ${error.message}`);
+        return 1;
+    }
+}
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}

package/build/src/cli/validate-workflow-artifacts.js

@@ -467,7 +467,11 @@ function validateSidecarGroup(inputs, markdown, requireSidecars, requireCritique
                 if (bundleValue) {
                     const claims = Array.isArray(bundleValue.claims) ? bundleValue.claims : [];
                     const critiqueClaims = claims.filter((c) => c && c.claimType === "workflow.critique.review");
-                    if (critiqueClaims.some((c) => c.value === "fail" || c.status === "disputed"))
+                    // #282: a historical fail/disputed critique that has been explicitly superseded by a later
+                    // resolving write (metadata.superseded_by) is retained structurally as history and does NOT
+                    // block a top-level pass — only a LIVE (non-superseded) fail/disputed critique blocks.
+                    const isSuperseded = (c) => c && c.metadata && typeof c.metadata === "object" && c.metadata.superseded_by;
+                    if (critiqueClaims.some((c) => (c.value === "fail" || c.status === "disputed") && !isSuperseded(c)))
                         issues.push({ path: trustBundlePath, message: "required critique must pass" });
                 }
             }

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

@@ -581,7 +581,11 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         // (workflow-artifact-cleanup-audit) and validators can detect the promotion claim without a
         // new manifest entry. It rides alongside any waiver in a single merged metadata object.
         const promotionMeta = (check._promotion && typeof check._promotion === "object") ? check._promotion : null;
-        const claimMetadata = (waiver || promotionMeta) ? { ...(waiver ? { waiver } : {}), ...(promotionMeta ? { promotion: promotionMeta } : {}) } : null;
+        // #268: stamp a stable origin discriminator so checksFromBundle / critiquesFromBundle can
+        // distinguish check vs critique vs acceptance claims across round-trips even under --flow-id,
+        // where all three collapse onto the same declared claimType (and a command-less critique claim
+        // would otherwise be re-absorbed as a test_output check → permanent [not-run] divergence).
+        const claimMetadata = { origin: "check", check_kind: String(check.kind ?? "external"), ...(waiver ? { waiver } : {}), ...(promotionMeta ? { promotion: promotionMeta } : {}) };
         const claimEvents = [];
         if (evStatus) {
             const evt = { id: `evt:${claimId}`, claimId, status: evStatus, actor: "flow-agents/workflow-sidecar", method: "validation", evidenceIds: [evId], createdAt: ts, verifiedAt: ts };
@@ -640,13 +644,13 @@ 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 };
+            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" } };
             const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [], events: claimEvents, policies: [declaredPolicy] });
             claims.push({ ...declaredClaimObj, status: declaredStatus });
         }
         else {
             // No active flow step — only the workflow.* primary claim (legitimate no-flow fallback path).
-            const claimObj = { id: claimId, subjectType: "workflow-acceptance-criterion", subjectId, facet: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: policy.id };
+            const claimObj = { id: claimId, subjectType: "workflow-acceptance-criterion", subjectId, facet: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: criterion.status, createdAt: ts, updatedAt: ts, impactLevel: "high", verificationPolicyId: policy.id, metadata: { origin: "acceptance" } };
             const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [policy] });
             claims.push({ ...claimObj, status: derivedStatus });
         }
@@ -657,10 +661,23 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
             continue;
         const subjectId = `${slug}/${c.id}`;
         const fieldOrBehavior = String(c.summary ?? c.verdict ?? c.id);
-        const claimId = generateClaimId(subjectId, "flow-agents.workflow", fieldOrBehavior);
+        // #267/#282: a critique carrying `superseded_by` is retained as HISTORY — a prior write for
+        // this critique id that a later, same-reviewer critique resolved. It is preserved structurally
+        // (status "superseded" + first-class metadata.superseded_by), but is excluded from reconcile
+        // evaluation and from the "critique pass cannot include fail members" validator rule.
+        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 critMeta = { origin: "critique", reviewer: critiqueReviewer, reviewed_at: critiqueReviewedAt, ...(supersededBy ? { superseded_by: supersededBy } : {}) };
+        // 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 claimId = generateClaimId(subjectId, "flow-agents.workflow", claimIdSalt);
         const legacyClaimType = "workflow.critique.review";
         const policy = ensurePolicy(legacyClaimType, "medium", []);
-        const evStatus = critiqueToEventStatus(String(c.verdict ?? ""), c.findings ?? []);
+        // A superseded write emits NO verification event (its status is "superseded" directly).
+        const evStatus = supersededBy ? null : critiqueToEventStatus(String(c.verdict ?? ""), c.findings ?? []);
         const claimEvents = [];
         if (evStatus) {
             const evt = { id: `evt:${claimId}`, claimId, status: evStatus, actor: "flow-agents/workflow-sidecar", method: "validation", evidenceIds: [], createdAt: ts, verifiedAt: ts };
@@ -669,17 +686,16 @@ export async function buildTrustBundle(slug, timestamp, checks, criteria, critiq
         }
         // P-d: declared-only when active flow/step present (shadow retired); no-flow path unchanged.
         const declared = matchExpectsEntry("critique");
-        if (declared) {
-            // Declared kit-typed claim only — no legacy shadow (ADR 0016 P-d).
-            const declaredPolicy = ensurePolicy(declared.claimType, "medium", []);
-            const declaredClaimObj = { id: claimId, subjectType: declared.subjectType, subjectId, facet: "flow-agents.workflow", claimType: declared.claimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: declaredPolicy.id };
-            const { status: declaredStatus } = deriveClaimStatus({ claim: declaredClaimObj, evidence: [], events: claimEvents, policies: [declaredPolicy] });
-            claims.push({ ...declaredClaimObj, status: declaredStatus });
+        const claimType = declared ? declared.claimType : legacyClaimType;
+        const subjectType = declared ? declared.subjectType : "workflow-critique";
+        const claimPolicy = declared ? ensurePolicy(declared.claimType, "medium", []) : policy;
+        const claimObj = { id: claimId, subjectType, subjectId, facet: "flow-agents.workflow", claimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: claimPolicy.id, metadata: critMeta };
+        if (supersededBy) {
+            // History: status is "superseded" directly (no verification event); excluded from evaluation.
+            claims.push({ ...claimObj, status: "superseded" });
         }
         else {
-            // No active flow step — only the workflow.* primary claim (legitimate no-flow fallback path).
-            const claimObj = { id: claimId, subjectType: "workflow-critique", subjectId, facet: "flow-agents.workflow", claimType: legacyClaimType, fieldOrBehavior, value: c.verdict, createdAt: ts, updatedAt: ts, impactLevel: "medium", verificationPolicyId: policy.id };
-            const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [policy] });
+            const { status: derivedStatus } = deriveClaimStatus({ claim: claimObj, evidence: [], events: claimEvents, policies: [claimPolicy] });
             claims.push({ ...claimObj, status: derivedStatus });
         }
     }
@@ -1504,67 +1520,70 @@ export function writeState(dir, slug, status, phase, timestamp, summary, next =
 // After 4c, evidence.json and critique.json are no longer written.
 // Extract checks and critiques from the existing trust.bundle for callers that
 // need to rebuild the bundle (e.g. record-critique, record-learning).
-// ADR 0016 Abstraction A (Step 0 Q3 carry-forward): build the set of declared
-// claimTypes from the active flow step for the session at `dir`. When no active
-// flow is present (workflow.* sessions), returns an empty set so every existing
-// predicate is unchanged. When a FlowDefinition-driven session (builder.build)
-// is active, the set contains the kit-typed claimTypes (e.g. "builder.verify.tests",
-// "builder.verify.policy-compliance") so round-trip helpers broaden their filters
-// to include declared claims alongside the legacy workflow.* ones.
+// #268/#344: buildTrustBundle stamps a stable origin discriminator ("check" | "acceptance" |
+// "critique") plus check_kind (for origin "check") on EVERY claim it writes. These stamps are
+// AUTHORITATIVE and the ONLY way checksFromBundle/critiquesFromBundle (and evidenceClean/
+// critiqueClean below) classify a claim.
 //
-// Safety guard: current.json in the runtime artifact root records the CURRENTLY ACTIVE
-// session via artifact_dir. If current.json points to a different session than `dir`
-// (e.g. another session was the last to call advance-state --flow-definition), we
-// return an empty set so declared-type predicates are NOT applied to the wrong session.
-// This prevents a cross-session active_flow_id from broadening claim filters for
-// unrelated sessions (which would cause spurious evidence/critique check behavior).
-function declaredClaimTypesFor(dir) {
-    const flowAgentsDir = path.dirname(dir);
-    // Verify that current.json points to `dir` before reading active flow step.
-    // If it points to a different session, return empty set (zero behavior change).
-    const currentFile = path.join(flowAgentsDir, "current.json");
-    try {
-        const current = JSON.parse(fs.readFileSync(currentFile, "utf8"));
-        const artDir = typeof current["artifact_dir"] === "string" ? current["artifact_dir"] : null;
-        if (!artDir)
-            return new Set();
-        const resolvedCurrent = path.resolve(flowAgentsDir, artDir);
-        if (path.resolve(dir) !== resolvedCurrent)
-            return new Set();
-    }
-    catch {
-        return new Set();
-    }
-    const activeStep = resolveActiveFlowStep(flowAgentsDir);
-    if (!activeStep || activeStep.gateExpects.length === 0)
-        return new Set();
-    return new Set(activeStep.gateExpects.map((e) => e.bundle_claim.claimType));
-}
-function checksFromBundle(dir, declaredClaimTypes = new Set()) {
+// Hard cutover (owner directive, no legacy fallbacks): there is deliberately no claimType-
+// derivation fallback for unstamped claims. A prior version of this file fell back to
+// classifying an unstamped claim by claimType heuristic — that fallback WAS the #268 defect
+// kept reachable (a no-evidence declared claim silently re-absorbed as a command-less
+// test_output check, and a critique claim silently re-absorbed as a check, corrupting the
+// round-trip catastrophically under --flow-id). An unstamped claim means the bundle predates
+// #344 and must be regenerated, not silently reclassified — see requireStampedClaim below.
+function claimOrigin(claim) {
+    const md = claim && claim.metadata;
+    return md && typeof md === "object" && typeof md.origin === "string" && md.origin.length > 0 ? String(md.origin) : null;
+}
+// Fails loud — never silent, never a heuristic reclassification — when a claim in `dir`'s
+// trust.bundle lacks its metadata.origin stamp, or (for an origin==="check" claim) its
+// metadata.check_kind stamp. Names the session dir and the remedy so the caller can regenerate
+// a fresh, fully-stamped bundle instead of reading a pre-supersession one.
+function requireStampedClaim(claim, dir) {
+    if (!claim || typeof claim !== "object")
+        die(`trust.bundle in ${dir} contains a malformed claim entry — cannot read.`);
+    const remedy = `re-record evidence to regenerate: npm run workflow:sidecar -- record-evidence ${dir} --verdict <verdict> --check-json <...>`;
+    const origin = claimOrigin(claim);
+    if (!origin) {
+        die(`pre-supersession trust.bundle in ${dir}: claim '${claim.id ?? "<unknown>"}' has no metadata.origin stamp (this bundle predates #344's origin/check_kind stamping and cannot be read authoritatively) — ${remedy}`);
+    }
+    if (origin === "check") {
+        const md = (claim.metadata && typeof claim.metadata === "object") ? claim.metadata : {};
+        if (typeof md.check_kind !== "string" || md.check_kind.length === 0) {
+            die(`pre-supersession trust.bundle in ${dir}: check claim '${claim.id ?? "<unknown>"}' has metadata.origin but no metadata.check_kind stamp (this bundle predates #344's stamping and cannot be read authoritatively) — ${remedy}`);
+        }
+    }
+    return origin;
+}
+function checksFromBundle(dir) {
     const bundle = loadJson(path.join(dir, "trust.bundle"));
+    const allClaims = Array.isArray(bundle.claims) ? bundle.claims : [];
+    // Validate stamps on every claim up front — any unstamped claim anywhere in the bundle marks
+    // it pre-supersession, regardless of whether it is check/acceptance/critique-typed.
+    for (const claim of allClaims)
+        requireStampedClaim(claim, dir);
     if (!Array.isArray(bundle.evidence))
         return [];
-    const allClaims = Array.isArray(bundle.claims) ? bundle.claims : [];
     const claimById = new Map();
     for (const c of allClaims)
         if (c && c.id)
             claimById.set(c.id, c);
     const seen = new Set();
     const checks = [];
+    const kindOf = (claim) => String(claim.metadata.check_kind);
     for (const ev of bundle.evidence) {
         if (!ev || !ev.claimId)
             continue;
         const claim = claimById.get(ev.claimId);
         if (!claim)
             continue;
-        const ct = String(claim.claimType || "");
-        // ADR 0016 Step 0: broaden to include declared kit-typed claims alongside workflow.check.*
-        if (!ct.startsWith("workflow.check.") && !declaredClaimTypes.has(ct))
+        if (claimOrigin(claim) !== "check")
             continue;
         if (seen.has(ev.claimId))
             continue;
         seen.add(ev.claimId);
-        const kind = ct.startsWith("workflow.check.") ? (ct.replace("workflow.check.", "") || "external") : (ct.split(".").pop() || "external");
+        const kind = kindOf(claim);
         const status = claim.value ?? "not_verified";
         const check = { id: String(claim.subjectId || "").split("/").pop() || ev.claimId, kind, status, summary: claim.fieldOrBehavior || "" };
         if (ev.execution && typeof ev.execution.label === "string")
@@ -1573,41 +1592,43 @@ function checksFromBundle(dir, declaredClaimTypes = new Set()) {
             check.evidenceType = ev.evidenceType;
         checks.push(check);
     }
-    // Also include check claims that have no evidence item (surface_trust_refs style)
+    // Also include check claims that have no evidence item (surface_trust_refs style).
     for (const claim of allClaims) {
         if (!claim)
             continue;
-        const ct = String(claim.claimType || "");
-        // ADR 0016 Step 0: broaden to include declared kit-typed claims alongside workflow.check.*
-        if (!ct.startsWith("workflow.check.") && !declaredClaimTypes.has(ct))
+        if (claimOrigin(claim) !== "check")
             continue;
         if (seen.has(claim.id))
             continue;
         seen.add(claim.id);
-        const kind = ct.startsWith("workflow.check.") ? (ct.replace("workflow.check.", "") || "external") : (ct.split(".").pop() || "external");
+        const kind = kindOf(claim);
         checks.push({ id: String(claim.subjectId || "").split("/").pop() || claim.id, kind, status: claim.value ?? "not_verified", summary: claim.fieldOrBehavior || "" });
     }
     return checks;
 }
-function critiquesFromBundle(dir, declaredClaimTypes = new Set()) {
+function critiquesFromBundle(dir) {
     const bundle = loadJson(path.join(dir, "trust.bundle"));
     if (!Array.isArray(bundle.claims))
         return [];
-    // ADR 0016 Step 0: broaden to include declared kit-typed critique claims alongside workflow.critique.review.
-    // P-d: exclude claims that have evidence items (evidence = check claims, not critique claims).
-    // This prevents check-type declared claims (e.g. builder.verify.tests) from being read back
-    // as critiques when declaredClaimTypes includes all gate expects[] types.
-    const evidenceClaimIds = new Set(Array.isArray(bundle.evidence) ? bundle.evidence.map((e) => e?.claimId).filter((id) => typeof id === "string") : []);
-    const critiqueClaims = bundle.claims.filter((c) => c && (c.claimType === "workflow.critique.review" || declaredClaimTypes.has(c.claimType)) && !evidenceClaimIds.has(c.id));
-    return critiqueClaims.map((c) => ({
-        id: String(c.subjectId || "").split("/").pop() || c.id,
-        verdict: c.value ?? "not_verified",
-        summary: c.fieldOrBehavior || "",
-        findings: [],
-        reviewer: "tool-code-reviewer",
-        reviewed_at: c.updatedAt || c.createdAt || now(),
-        artifact_refs: [],
-    }));
+    for (const c of bundle.claims)
+        requireStampedClaim(c, dir);
+    // A claim is a CRITIQUE when its origin is "critique" (authoritative — see requireStampedClaim
+    // above). reviewer / reviewed_at / superseded_by are read back from metadata so supersession
+    // (#267/#282) round-trips losslessly.
+    const critiqueClaims = bundle.claims.filter((c) => c && claimOrigin(c) === "critique");
+    return critiqueClaims.map((c) => {
+        const md = (c.metadata && typeof c.metadata === "object") ? c.metadata : {};
+        return {
+            id: String(c.subjectId || "").split("/").pop() || c.id,
+            verdict: c.value ?? "not_verified",
+            summary: c.fieldOrBehavior || "",
+            findings: [],
+            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()),
+            artifact_refs: [],
+            ...(typeof md.superseded_by === "string" && md.superseded_by.length > 0 ? { superseded_by: md.superseded_by } : {}),
+        };
+    });
 }
 // ─────────────────────────────────────────────────────────────────────────────
 /**
@@ -1662,7 +1683,11 @@ async function recordEvidence(p) {
     const _existingCriteria = Array.isArray(_existingAcceptance.criteria) ? _existingAcceptance.criteria : [];
     const _criteriaStatus = verdict === "pass" ? "pass" : verdict === "fail" ? "fail" : "not_verified";
     const _criteriaForBundle = _existingCriteria.map((c) => ({ ...c, status: _criteriaStatus }));
-    assertBundleWritten(await writeTrustBundle(dir, slug, ts, checks, _criteriaForBundle, []));
+    // #268: preserve any existing critique claims (including superseded history) instead of dropping
+    // them — record-evidence previously hardcoded critiques:[] here, silently erasing finding history
+    // whenever it ran after a critique existed.
+    const _existingCritiques = critiquesFromBundle(dir);
+    assertBundleWritten(await writeTrustBundle(dir, slug, ts, checks, _criteriaForBundle, _existingCritiques));
     const stateStatus = verdict === "pass" ? "verified" : verdict === "fail" ? "failed" : "not_verified";
     writeState(dir, slug, stateStatus, "verification", ts, "Evidence recorded.");
     return 0;
@@ -1826,11 +1851,10 @@ async function promote(p) {
     // Add the promotion claim WITHOUT dropping the session's existing verification
     // evidence/criteria/critiques (mirror record-critique's merge pattern). Drop any prior
     // "promotion" check so re-running promote is idempotent rather than duplicating.
-    const _dct = declaredClaimTypesFor(dir);
-    const existingChecks = checksFromBundle(dir, _dct).filter((c) => c.id !== "promotion");
+    const existingChecks = checksFromBundle(dir).filter((c) => c.id !== "promotion");
     const _acc = loadJson(path.join(dir, "acceptance.json"));
     const criteria = Array.isArray(_acc.criteria) ? _acc.criteria : [];
-    const critiques = critiquesFromBundle(dir, _dct);
+    const critiques = critiquesFromBundle(dir);
     assertBundleWritten(await writeTrustBundle(dir, slug, ts, [...existingChecks, promotionCheck], criteria, critiques));
     // Auditable record of what was promoted where (companion to the trust.bundle claim).
     writeJson(path.join(dir, "promotion.json"), { ...sidecarBase(slug), ...promotionMarker, summary });
@@ -1924,14 +1948,31 @@ async function recordCritique(p) {
     // Fall back to critique.json for legacy sessions that still have it on disk.
     const existingCritiqueJson = loadJson(path.join(dir, "critique.json"), { critiques: [] });
     const legacyCritiques = Array.isArray(existingCritiqueJson.critiques) ? existingCritiqueJson.critiques : [];
-    const _dctCritique = declaredClaimTypesFor(dir);
-    const bundleCritiques = legacyCritiques.length === 0 ? critiquesFromBundle(dir, _dctCritique) : legacyCritiques;
+    const bundleCritiques = legacyCritiques.length === 0 ? critiquesFromBundle(dir) : legacyCritiques;
     const critique = { id: opt(p, "id") || "review", reviewer: opt(p, "reviewer", "tool-code-reviewer"), reviewed_at: opt(p, "timestamp", now()), verdict: opt(p, "verdict", "pass"), summary: opt(p, "summary"), artifact_refs: opts(p, "artifact-ref"), findings: opts(p, "finding-json").map((v) => normalizeFinding(parseJson(v, "--finding-json"))) };
-    const critiques = [...bundleCritiques, critique];
     if (critique.verdict === "pass" && critique.findings.some((f) => f.status === "open"))
         die("required critique must pass");
+    // #267/#282: supersede-by-critique-id. The latest write for a critique id wins for
+    // reconcile / status / validator purposes; each prior LIVE write for the same id is RETAINED as
+    // history (status "superseded", first-class metadata.superseded_by) but excluded from evaluation.
+    // Supersession is REVIEWER-SCOPED (anti-gaming): a write may only supersede a prior live critique
+    // of the same id written by the SAME reviewer — a different reviewer's disputed finding is never
+    // buried, so it stays live and continues to block. DOCUMENTED GAP: reviewer identity is the
+    // free-form --reviewer string (with a default); there is no cryptographic worker-vs-reviewer
+    // distinction yet — that lands with the runtime actor-identity slice (#287/#290). Same-reviewer-
+    // string scoping is the strongest honest enforcement available today and matches the granularity
+    // the critique record already has.
+    const _supersedeMarker = `${critique.id}@${critique.reviewed_at}`;
+    const _mergedCritiques = bundleCritiques.map((e) => {
+        const eSuperseded = typeof e.superseded_by === "string" && e.superseded_by.length > 0;
+        const eReviewer = String(e.reviewer ?? "tool-code-reviewer");
+        if (e.id === critique.id && !eSuperseded && eReviewer === critique.reviewer)
+            return { ...e, superseded_by: _supersedeMarker };
+        return e;
+    });
+    const critiques = [..._mergedCritiques, critique];
     // Phase 4c: build bundle from raw inputs; read checks from trust.bundle (evidence.json no longer written).
-    const _critiqueEvChecks = checksFromBundle(dir, _dctCritique);
+    const _critiqueEvChecks = checksFromBundle(dir);
     const _critiqueAccCriteria = Array.isArray(loadJson(path.join(dir, "acceptance.json")).criteria) ? loadJson(path.join(dir, "acceptance.json")).criteria : [];
     assertBundleWritten(await writeTrustBundle(dir, slug, critique.reviewed_at, _critiqueEvChecks, _critiqueAccCriteria, critiques));
     return 0;
@@ -2327,26 +2368,23 @@ async function recordLearning(p) {
     writeJson(path.join(dir, "learning.json"), { ...sidecarBase(slug), status, updated_at: timestamp, records });
     writeState(dir, slug, "accepted", "learning", timestamp, opt(p, "summary"));
     // Phase 4c: build bundle from raw inputs; read checks/critiques from trust.bundle (bespoke sidecars no longer written).
-    // ADR 0016 Step 0: pass declaredClaimTypes so declared builder.* claims survive the round-trip.
-    const _dctLearning = declaredClaimTypesFor(dir);
-    const _learningChecks = checksFromBundle(dir, _dctLearning);
+    // #268/#344: declared builder.* claims survive the round-trip via their authoritative origin stamp.
+    const _learningChecks = checksFromBundle(dir);
     const _learningCriteria = Array.isArray(loadJson(path.join(dir, "acceptance.json")).criteria) ? loadJson(path.join(dir, "acceptance.json")).criteria : [];
-    const _learningCritiques = critiquesFromBundle(dir, _dctLearning);
+    const _learningCritiques = critiquesFromBundle(dir);
     assertBundleWritten(await writeTrustBundle(dir, slug, timestamp, _learningChecks, _learningCriteria, _learningCritiques));
     return 0;
 }
-function evidenceClean(dir, declaredClaimTypes = new Set()) {
-    // Phase 4c: read from trust.bundle (sole verification artifact); fall back to evidence.json for legacy sessions.
-    // ADR 0016 Step 0: declaredClaimTypes broadens the filter to include kit-typed check claims
-    // (e.g. builder.verify.tests) in addition to workflow.check.* for FlowDefinition-driven sessions.
+function evidenceClean(dir) {
+    // Phase 4c: read from trust.bundle (sole verification artifact); fall back to evidence.json for
+    // legacy (pre-bundle-era) sessions that never wrote a trust.bundle at all — unrelated to origin
+    // stamping. When a trust.bundle IS present, every claim must be stamped (requireStampedClaim);
+    // there is no claimType-derivation fallback for an unstamped claim (#268/#344).
     const bundle = loadJson(path.join(dir, "trust.bundle"));
     if (Array.isArray(bundle.claims)) {
-        const checkClaims = bundle.claims.filter((c) => {
-            if (!c)
-                return false;
-            const ct = String(c.claimType || "");
-            return ct.startsWith("workflow.check.") || declaredClaimTypes.has(ct);
-        });
+        for (const c of bundle.claims)
+            requireStampedClaim(c, dir);
+        const checkClaims = bundle.claims.filter((c) => c && claimOrigin(c) === "check");
         if (checkClaims.length === 0)
             return false;
         return checkClaims.every((c) => {
@@ -2354,7 +2392,7 @@ function evidenceClean(dir, declaredClaimTypes = new Set()) {
             return v === "pass" || v === "skip";
         });
     }
-    // Legacy fallback: evidence.json
+    // Legacy fallback: evidence.json (pre-bundle-era sessions with no trust.bundle at all)
     const e = loadJson(path.join(dir, "evidence.json"), {});
     return e.verdict === "pass" && Array.isArray(e.checks) && e.checks.length > 0 && e.checks.every((c) => {
         if (!(c.status === "pass" || c.status === "skip"))
@@ -2362,13 +2400,23 @@ function evidenceClean(dir, declaredClaimTypes = new Set()) {
         return !Array.isArray(c.standard_refs) || c.standard_refs.every((r) => ["junit", "sarif", "coverage", "veritas"].includes(r.standard));
     });
 }
-function critiqueClean(dir, declaredClaimTypes = new Set()) {
-    // Phase 4c: read from trust.bundle (sole verification artifact); fall back to critique.json for legacy sessions.
-    // ADR 0016 Step 0: declaredClaimTypes broadens the filter to include kit-typed critique claims
-    // (e.g. builder.verify.policy-compliance) in addition to workflow.critique.review.
+function critiqueClean(dir) {
+    // Phase 4c: read from trust.bundle (sole verification artifact); fall back to critique.json for
+    // legacy (pre-bundle-era) sessions — unrelated to origin stamping. When a trust.bundle IS
+    // present, every claim must be stamped (requireStampedClaim); no claimType-derivation fallback
+    // for an unstamped claim (#268/#344).
     const bundle = loadJson(path.join(dir, "trust.bundle"));
     if (Array.isArray(bundle.claims)) {
-        const critiqueClaims = bundle.claims.filter((c) => c && (c.claimType === "workflow.critique.review" || declaredClaimTypes.has(c.claimType)));
+        for (const c of bundle.claims)
+            requireStampedClaim(c, dir);
+        const critiqueClaims = bundle.claims.filter((c) => {
+            if (!c)
+                return false;
+            // #267/#282: superseded history is not evaluated for cleanliness.
+            if (c.metadata && typeof c.metadata === "object" && c.metadata.superseded_by)
+                return false;
+            return claimOrigin(c) === "critique";
+        });
         if (critiqueClaims.length === 0)
             return false; // no critique written yet
         return critiqueClaims.every((c) => {
@@ -2410,10 +2458,9 @@ async function dogfoodPass(p) {
         if (checks.some((c) => c.status !== "pass" && c.status !== "skip"))
             die("clean evidence requires all non-skipped checks to pass");
         // Phase 4c: evidence check reads from trust.bundle (sole verification artifact); legacy evidence.json fallback in evidenceClean.
-        // ADR 0016 Step 0: pass declaredClaimTypes so builder.* check/critique claims count as clean evidence.
-        const _dctDogfood = declaredClaimTypesFor(dir);
-        const _hasBundleEvidence = fs.existsSync(path.join(dir, "trust.bundle")) && evidenceClean(dir, _dctDogfood);
-        const _hasLegacyEvidence = fs.existsSync(path.join(dir, "evidence.json")) && evidenceClean(dir, _dctDogfood);
+        // #268/#344: builder.* check/critique claims count as clean evidence via their authoritative origin stamp.
+        const _hasBundleEvidence = fs.existsSync(path.join(dir, "trust.bundle")) && evidenceClean(dir);
+        const _hasLegacyEvidence = fs.existsSync(path.join(dir, "evidence.json")) && evidenceClean(dir);
         if (!_hasBundleEvidence && !_hasLegacyEvidence && fs.existsSync(path.join(dir, "trust.bundle")))
             die("cannot mark clean without passing evidence");
         if (!_hasBundleEvidence && !_hasLegacyEvidence && !fs.existsSync(path.join(dir, "trust.bundle")) && fs.existsSync(path.join(dir, "evidence.json")))
@@ -2426,10 +2473,10 @@ async function dogfoodPass(p) {
                 normalizeFinding(parseJson(value, "--finding-json"));
             if (newCritiqueVerdict !== "pass")
                 die(opt(p, "release-decision") ? "requires clean critique" : "requires clean critique before recording pass evidence");
-            if (!opt(p, "critique-id") && !critiqueClean(dir, _dctDogfood))
+            if (!opt(p, "critique-id") && !critiqueClean(dir))
                 die("requires passing critique");
             // Phase 4c: if existing state has a dirty critique (in bundle or legacy critique.json), block even when adding a new critique-id.
-            if (!critiqueClean(dir, _dctDogfood) && (fs.existsSync(path.join(dir, "trust.bundle")) || fs.existsSync(path.join(dir, "critique.json"))))
+            if (!critiqueClean(dir) && (fs.existsSync(path.join(dir, "trust.bundle")) || fs.existsSync(path.join(dir, "critique.json"))))
                 die(opt(p, "release-decision") ? "requires clean critique" : "requires clean critique before recording pass evidence");
         }
     }

package/build/src/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { basename } from "node:path";
 import { main as effectiveBacklogSettings } from "./cli/effective-backlog-settings.js";
+import { main as effectiveAssignmentProviderSettings } from "./cli/effective-assignment-provider-settings.js";
+import { main as assignmentProvider } from "./cli/assignment-provider.js";
 import { main as consoleLearningProjection } from "./cli/console-learning-projection.js";
 import { main as kit } from "./cli/kit.js";
 import { main as fixtureRetirementAudit } from "./cli/fixture-retirement-audit.js";
@@ -24,6 +26,8 @@ const availableCommands = new Map([
     ["build-bundles", () => buildBundles()],
     ["console-learning-projection", consoleLearningProjection],
     ["context-map", contextMap],
+    ["assignment-provider", assignmentProvider],
+    ["effective-assignment-provider-settings", effectiveAssignmentProviderSettings],
     ["effective-backlog-settings", effectiveBacklogSettings],
     ["fixture-retirement-audit", fixtureRetirementAudit],
     ["kit", kit],
@@ -46,6 +50,8 @@ const aliases = new Map([
     ["flow-agents-build-bundles", "build-bundles"],
     ["flow-agents-console-learning-projection", "console-learning-projection"],
     ["flow-agents-context-map", "context-map"],
+    ["flow-agents-assignment-provider", "assignment-provider"],
+    ["flow-agents-effective-assignment-provider-settings", "effective-assignment-provider-settings"],
     ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
     ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
     ["flow-agents-kit", "kit"],

package/build/src/tools/validate-source-tree.js

@@ -93,6 +93,7 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/lib/resolve-formatter.js", { category: "shared hook library", requiredNeedles: ["resolveFormatter"] }],
 ]);
 const fixtureOwnerPolicies = new Map([
+    ["evals/fixtures/assignment-provider", { owners: ["evals/integration/test_assignment_provider_local_file.sh", "evals/integration/test_assignment_provider_github.sh", "evals/integration/test_pull_work_assignment_join.sh"], classification: "AssignmentProvider local-file and GitHub render/status fixtures (#290)" }],
     ["evals/fixtures/backlog-provider-settings", { owners: ["evals/integration/test_effective_backlog_settings.sh"], classification: "settings precedence fixtures" }],
     ["evals/fixtures/builder-kit-workflow-state", { owners: ["evals/static/test_workflow_skills.sh"], classification: "Builder Kit workflow-state fixtures" }],
     ["evals/fixtures/console-learning-projection", { owners: ["evals/integration/test_console_learning_projection.sh"], classification: "console learning projection fixtures" }],