@kontourai/flow-agents 1.4.0 → 2.0.1

package/build/src/tools/generate-context-map.js

@@ -10,19 +10,20 @@ const dirDescriptions = {
     context: "Shared contracts, routing notes, templates, and reusable guidance.",
     docs: "Long-lived project documentation and GitHub Pages content.",
     evals: "Static, integration, install, and behavioral eval fixtures.",
-    powers: "Optional MCP/tool integration packs.",
+    powers: "Optional MCP/tool capability bundles.",
     prompts: "Reusable prompt entry points.",
     schemas: "JSON Schema contracts for machine-readable workflow artifacts.",
     scripts: "Build, validation, hook, telemetry, workflow, and import/export utilities.",
     skills: "On-demand capability instructions and workflow primitives.",
 };
-const workflowSkills = new Set(["idea-to-backlog", "pull-work", "plan-work", "execute-plan", "review-work", "verify-work", "evidence-gate", "release-readiness", "learning-review", "deliver", "fix-bug", "tdd-workflow"]);
+const workflowSkills = new Set(["idea-to-backlog", "pull-work", "plan-work", "execute-plan", "review-work", "verify-work", "evidence-gate", "gate-review", "release-readiness", "learning-review", "deliver", "continue-work", "fix-bug", "tdd-workflow"]);
 const commands = [
     ["Source tree", "npm run validate:source"],
     ["Static suite", "bash evals/run.sh static"],
     ["Integration suite", "bash evals/run.sh integration"],
     ["Workflow artifacts", "npm run workflow:validate-artifacts -- --require-sidecars --require-critique .flow-agents/<slug>"],
     ["Workflow sidecars", "npm run workflow:sidecar -- --help"],
+    ["Claim lookup", "npm run workflow:sidecar -- claim <id> <dir>"],
     ["Context map drift", "npm run context-map:check"],
     ["Bundle build", "npm run build:bundles"],
 ];
@@ -154,17 +155,6 @@ function powers() {
     const dir = path.join(root, "powers");
     return fs.readdirSync(dir).sort().flatMap((name) => exists(path.join(dir, name, "POWER.md")) ? [[name, rel(path.join(dir, name, "POWER.md"))]] : []);
 }
-function packs() {
-    const data = loadJson(path.join(root, "packaging/packs.json"));
-    return (data.packs ?? []).map((pack) => [
-        String(pack.name ?? ""),
-        pack.default ? "yes" : "no",
-        String(Array.isArray(pack.skills) ? pack.skills.length : 0),
-        String(Array.isArray(pack.agents) ? pack.agents.length : 0),
-        String(Array.isArray(pack.powers) ? pack.powers.length : 0),
-        oneLine(String(pack.description ?? "")),
-    ]);
-}
 function latestRuntimeStates(includeRuntime) {
     if (!includeRuntime) {
         return [
@@ -205,9 +195,6 @@ function render(includeRuntime) {
         "## Support Skills", "", ...markdownTable(["Skill", "Source", "When To Load"], supportRows), "",
         "## Agents", "", ...markdownTable(["Agent", "Model", "Tools", "Role"], agents()), "",
         "## Optional Powers", "", ...markdownTable(["Power", "Source"], powers()), "",
-        "## Packs", "",
-        "Pack composition is defined in `packaging/packs.json`. The current builder exports pack metadata in bundle catalogs, and generated install scripts support opt-in `FLOW_AGENTS_PACKS` filtering while leaving all packs installed by default.", "",
-        ...markdownTable(["Pack", "Default", "Skills", "Agents", "Powers", "Purpose"], packs()), "",
         "## Current Workflow State", "", ...latestRuntimeStates(includeRuntime), "",
         "## Context Loading Rules", "",
         "- For delivery work, load `deliver`, then the specific primitive skill for the current phase.",

package/build/src/tools/validate-source-tree.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export declare function main(argv?: string[]): number;
+export declare function main(argv?: string[]): Promise<number>;

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

@@ -2,7 +2,7 @@
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { validateKitRepository as validateFlowKitRepository } from "../flow-kit/validate.js";
 import { loadJson, readText, rel, root, walkFiles } from "./common.js";
 class Reporter {
     errors = [];
@@ -11,14 +11,10 @@ class Reporter {
         this.fail(message); }
 }
 const manifestPath = path.join(root, "packaging/manifest.json");
-const packsPath = path.join(root, "packaging/packs.json");
 const kitsCatalogPath = path.join(root, "kits/catalog.json");
 const flowRoot = process.env.FLOW_CLI_ROOT ? path.resolve(process.env.FLOW_CLI_ROOT) : "";
 const flowSchemaPath = flowRoot ? path.join(flowRoot, "schemas", "flow-definition.schema.json") : "";
 const flowCliPath = flowRoot ? ["dist/cli.js", "src/cli.js"].map((candidate) => path.join(flowRoot, candidate)).find((candidate) => fs.existsSync(candidate)) ?? path.join(flowRoot, "dist/cli.js") : "";
-const kitIdRe = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/;
-const kitAssetSections = new Set(["skills", "docs", "adapters", "evals", "assets"]);
-const kitTopLevelKeys = new Set(["schema_version", "id", "name", "product_name", "description", "flows", ...kitAssetSections]);
 const textRefExtensions = new Set([".md", ".yaml", ".yml", ".json", ".sh", ".js", ".toml"]);
 const ignoredRefDirs = new Set(["node_modules", "__pycache__", ".pytest_cache", ".cache"]);
 const legacyRefRe = /(?<![A-Za-z0-9_.-])(?:agents|agent-cards|context|evals|lib|powers|prompts|scripts|skills)\/[A-Za-z0-9_./@:+-]+/g;
@@ -32,10 +28,8 @@ const mirroredFiles = new Map([
 ]);
 const publicScriptWrappers = new Map([
     ["scripts/build-universal-bundles.js", { target: "../build/src/tools/build-universal-bundles.js", significantLines: [
-                "// Supports FLOW_AGENTS_PACKS through the TypeScript bundle builder.",
                 'import("../build/src/tools/build-universal-bundles.js").then(({ main }) => process.exit(main()));',
             ] }],
-    ["scripts/filter-installed-packs.js", { target: "../build/src/tools/filter-installed-packs.js", significantLines: ['import("../build/src/tools/filter-installed-packs.js").then(({ main }) => process.exit(main(process.argv.slice(2))));'] }],
     ["scripts/generate-context-map.js", { target: "../build/src/tools/generate-context-map.js", significantLines: ['import("../build/src/tools/generate-context-map.js").then(({ main }) => process.exit(main(process.argv.slice(2))));'] }],
     ["scripts/kit.js", { target: "../build/src/cli/kit.js", significantLines: ['import("../build/src/cli/kit.js").then(({ main }) => main().then((code) => process.exit(code)));'] }],
     ["scripts/pull-work-provider.js", { target: "../build/src/cli/pull-work-provider.js", significantLines: ['import("../build/src/cli/pull-work-provider.js").then(({ main }) => process.exit(main()));'] }],
@@ -62,6 +56,7 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/codex-telemetry-hook.js", { category: "telemetry shim", requiredNeedles: ["codex", "telemetry"] }],
     ["scripts/hooks/run-hook.js", { category: "hook runner", requiredNeedles: ["isHookEnabled", "Path traversal rejected"] }],
     ["scripts/hooks/config-protection.js", { category: "policy hook", requiredNeedles: ["Config Protection Hook"] }],
+    ["scripts/hooks/evidence-capture.js", { category: "policy hook", requiredNeedles: ["Evidence Capture Hook"] }],
     ["scripts/hooks/governance-audit.sh", { category: "policy hook", requiredNeedles: ["governance-audit.sh", "audit_emit"] }],
     ["scripts/hooks/opencode-hook-adapter.js", { category: "runtime adapter", requiredNeedles: ["opencode", "run-hook.js"] }],
     ["scripts/hooks/opencode-telemetry-hook.js", { category: "telemetry shim", requiredNeedles: ["opencode", "telemetry"] }],
@@ -78,6 +73,7 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/desktop-notify.sh", { category: "local notification helper", requiredNeedles: ["desktop-notify.sh", "osascript"] }],
     ["scripts/hooks/lib/audit-transport.sh", { category: "shared hook library", requiredNeedles: ["audit_emit"] }],
     ["scripts/hooks/lib/hook-flags.js", { category: "shared hook library", requiredNeedles: ["isHookEnabled"] }],
+    ["scripts/hooks/lib/liveness-read.js", { category: "shared hook library", requiredNeedles: ["freshHolders", "readLivenessEvents"] }],
     ["scripts/hooks/lib/patterns.sh", { category: "shared hook library", requiredNeedles: ["_detect_secrets"] }],
     ["scripts/hooks/lib/resolve-formatter.js", { category: "shared hook library", requiredNeedles: ["resolveFormatter"] }],
 ]);
@@ -196,81 +192,7 @@ function validateManifest(reporter, manifest, agentNames) {
     for (const agent of manifest.codex?.excluded_agents ?? [])
         reporter.check(agentNames.has(agent), `${rel(manifestPath)}: codex excluded agent '${agent}' does not exist`);
 }
-function validatePacksManifest(reporter, agentNames) {
-    const data = tryLoadJson(packsPath, reporter);
-    if (!data || typeof data !== "object")
-        return;
-    reporter.check(data.schema_version === "1.0", `${rel(packsPath)}: schema_version must be 1.0`);
-    reporter.check(Array.isArray(data.packs) && data.packs.length > 0, `${rel(packsPath)}: packs must be a non-empty list`);
-    const skillNames = new Set(fs.readdirSync(path.join(root, "skills")).filter((name) => fs.existsSync(path.join(root, "skills", name, "SKILL.md"))));
-    const powerNames = new Set(fs.readdirSync(path.join(root, "powers")).filter((name) => fs.existsSync(path.join(root, "powers", name, "POWER.md"))));
-    const names = new Set();
-    const defaults = new Set();
-    const assigned = { skills: new Set(), agents: new Set(), powers: new Set() };
-    (Array.isArray(data.packs) ? data.packs : []).forEach((pack, index) => {
-        const name = pack?.name;
-        if (typeof name !== "string" || !/^[a-z][a-z0-9-]*$/.test(name)) {
-            reporter.fail(`${rel(packsPath)}: packs[${index}].name must be a kebab-case string`);
-            return;
-        }
-        if (names.has(name))
-            reporter.fail(`${rel(packsPath)}: duplicate pack name '${name}'`);
-        names.add(name);
-        if (pack.default === true)
-            defaults.add(name);
-        reporter.check(typeof pack.description === "string" && !!pack.description, `${rel(packsPath)}: pack '${name}' missing description`);
-        for (const [field, available] of [["skills", skillNames], ["agents", agentNames], ["powers", powerNames]]) {
-            const values = pack[field] ?? [];
-            reporter.check(Array.isArray(values), `${rel(packsPath)}: pack '${name}' .${field} must be a list`);
-            const seen = new Set();
-            for (const value of Array.isArray(values) ? values : []) {
-                if (typeof value !== "string") {
-                    reporter.fail(`${rel(packsPath)}: pack '${name}' .${field} entry is not a string`);
-                    continue;
-                }
-                if (seen.has(value))
-                    reporter.fail(`${rel(packsPath)}: pack '${name}' has duplicate ${field} entry '${value}'`);
-                seen.add(value);
-                assigned[field].add(value);
-                reporter.check(available.has(value), `${rel(packsPath)}: pack '${name}' references missing ${field.slice(0, -1)} '${value}'`);
-            }
-        }
-    });
-    reporter.check(defaults.has("core"), `${rel(packsPath)}: core pack must be default`);
-    const missingSkills = [...skillNames].filter((name) => !assigned.skills.has(name)).sort();
-    reporter.check(missingSkills.length === 0, `${rel(packsPath)}: skills missing from all packs: ${missingSkills.join(", ")}`);
-}
-function safeLocalPath(baseDir, pathText, label, reporter) {
-    if (typeof pathText !== "string" || !pathText) {
-        reporter.fail(`${label} must be a non-empty relative path`);
-        return undefined;
-    }
-    if (path.isAbsolute(pathText)) {
-        reporter.fail(`${label} must be relative; absolute paths are not allowed`);
-        return undefined;
-    }
-    if (pathText.split(/[\\/]/).includes("..")) {
-        reporter.fail(`${label} must stay inside the kit directory; '..' path traversal is not allowed`);
-        return undefined;
-    }
-    return path.join(baseDir, pathText);
-}
-function validateFlowDefinitionShape(file, data, reporter) {
-    const localCli = flowCliPath;
-    if (fs.existsSync(localCli)) {
-        const result = spawnSync("node", [localCli, "validate-definition", file, "--json"], { encoding: "utf8" });
-        if (result.status !== 0)
-            reporter.fail(`${rel(file)}: Flow validation failed: ${(result.stderr || result.stdout).trim()}`);
-        return;
-    }
-    if (!data || typeof data !== "object") {
-        reporter.fail(`${rel(file)}: Flow Definition must be an object`);
-        return;
-    }
-    for (const key of ["id", "version", "steps", "gates"])
-        reporter.check(key in data, `${rel(file)}: missing .${key}`);
-}
-function validateKitRepository(kitDir, reporter) {
+async function validateKitRepository(kitDir, reporter) {
     if (!fs.existsSync(kitDir) || !fs.statSync(kitDir).isDirectory()) {
         reporter.fail(`${rel(kitDir)}: kit directory does not exist`);
         return;
@@ -279,78 +201,10 @@ function validateKitRepository(kitDir, reporter) {
     reporter.check(fs.existsSync(kitJson), `${rel(kitDir)}: missing kit.json at repository root`);
     if (!fs.existsSync(kitJson))
         return;
-    const data = tryLoadJson(kitJson, reporter);
-    if (!data || typeof data !== "object")
-        return;
-    const unknownKeys = Object.keys(data).filter((key) => !kitTopLevelKeys.has(key)).sort();
-    if (unknownKeys.length)
-        reporter.fail(`${rel(kitJson)}: unsupported fields ${unknownKeys.join(", ")}; remove them or add them to the Flow Kit Repository contract`);
-    reporter.check(data.schema_version === "1.0", `${rel(kitJson)}: .schema_version must be "1.0"`);
-    reporter.check(typeof data.id === "string" && kitIdRe.test(data.id), `${rel(kitJson)}: .id must be a stable kebab-case string`);
-    reporter.check(typeof data.name === "string" && !!data.name.trim(), `${rel(kitJson)}: .name must be a non-empty string`);
-    for (const section of [...kitAssetSections].sort())
-        if (section in data) {
-            if (!Array.isArray(data[section])) {
-                reporter.fail(`${rel(kitJson)}: .${section} must be a list of relative asset paths or objects with path`);
-                continue;
-            }
-            const seenPaths = new Set();
-            const seenIds = new Set();
-            data[section].forEach((entry, index) => {
-                const pathValue = typeof entry === "string" ? entry : entry?.path;
-                const assetId = typeof entry === "object" ? entry.id : undefined;
-                if (typeof entry === "object") {
-                    const unknown = Object.keys(entry).filter((key) => !["id", "path", "description"].includes(key)).sort();
-                    if (unknown.length)
-                        reporter.fail(`${rel(kitJson)}: ${section}[${index}] has unsupported fields ${unknown.join(", ")}; use id, path, or description`);
-                }
-                if (assetId !== undefined && (typeof assetId !== "string" || !kitIdRe.test(assetId)))
-                    reporter.fail(`${rel(kitJson)}: ${section}[${index}].id must be a stable dot/kebab-case string`);
-                const assetPath = safeLocalPath(kitDir, pathValue, `${rel(kitJson)}: ${section}[${index}].path`, reporter);
-                if (!assetPath)
-                    return;
-                if (seenPaths.has(String(pathValue)))
-                    reporter.fail(`${rel(kitJson)}: ${section}[${index}].path duplicates '${pathValue}'; declare each asset once`);
-                seenPaths.add(String(pathValue));
-                if (typeof assetId === "string") {
-                    if (seenIds.has(assetId))
-                        reporter.fail(`${rel(kitJson)}: ${section}[${index}].id duplicates '${assetId}'; use a unique asset id`);
-                    seenIds.add(assetId);
-                }
-                reporter.check(fs.existsSync(assetPath), `${rel(kitJson)}: ${section}[${index}].path points at missing asset: ${pathValue}; add the file or remove the entry`);
-            });
-        }
-    if (!Array.isArray(data.flows) || !data.flows.length) {
-        reporter.fail(`${rel(kitJson)}: .flows must be a non-empty list; add at least one Flow Definition entry`);
-        return;
-    }
-    const seenIds = new Set();
-    const seenPaths = new Set();
-    data.flows.forEach((flow, index) => {
-        if (!flow || typeof flow !== "object") {
-            reporter.fail(`${rel(kitJson)}: flows[${index}] must be an object with id and path`);
-            return;
-        }
-        if (typeof flow.id !== "string" || !kitIdRe.test(flow.id))
-            reporter.fail(`${rel(kitJson)}: flows[${index}].id must be a stable dot/kebab-case string`);
-        else if (seenIds.has(flow.id))
-            reporter.fail(`${rel(kitJson)}: flows[${index}].id duplicates '${flow.id}'; use a unique Flow id`);
-        else
-            seenIds.add(flow.id);
-        const flowPath = safeLocalPath(kitDir, flow.path, `${rel(kitJson)}: flows[${index}].path`, reporter);
-        if (!flowPath)
-            return;
-        if (seenPaths.has(String(flow.path))) {
-            reporter.fail(`${rel(kitJson)}: flows[${index}].path duplicates '${flow.path}'; declare each Flow Definition once`);
-            return;
-        }
-        seenPaths.add(String(flow.path));
-        reporter.check(fs.existsSync(flowPath), `${rel(kitJson)}: flows[${index}].path points at missing Flow Definition: ${flow.path}; add the file or fix the path`);
-        if (fs.existsSync(flowPath))
-            validateFlowDefinitionShape(flowPath, tryLoadJson(flowPath, reporter), reporter);
-    });
+    for (const error of await validateFlowKitRepository(kitDir))
+        reporter.fail(error);
 }
-function validateKits(reporter) {
+async function validateKits(reporter) {
     reporter.check(fs.existsSync(path.join(root, "kits")), "kits directory missing");
     const catalog = tryLoadJson(kitsCatalogPath, reporter);
     const kits = catalog?.kits;
@@ -362,17 +216,17 @@ function validateKits(reporter) {
         console.log(fs.existsSync(localCli) ? `info: validating kit Flow Definitions with Flow CLI at ${localCli}` : `warning: Flow validator unavailable; source-tree check only verifies Flow Definition top-level shape`);
     else
         console.log("warning: Flow schema not configured; source-tree check only verifies Flow Definition top-level shape. Set FLOW_CLI_ROOT to enable Flow CLI validation. Container validation (kit.json core fields) will delegate to 'flow validate-kit' from @kontourai/flow when FLOW_CLI_ROOT is available.");
-    kits.forEach((entry, index) => {
+    for (const [index, entry] of kits.entries()) {
         const kitText = typeof entry === "string" ? entry : ["path", "directory", "dir", "id", "name"].map((key) => entry?.[key]).find((value) => typeof value === "string" && value);
         if (!kitText) {
             reporter.fail(`${rel(kitsCatalogPath)}: kits[${index}] missing path, directory, dir, id, or name`);
-            return;
+            continue;
         }
         const kitRef = String(kitText).startsWith("kits/") ? path.join(root, kitText) : path.join(root, "kits", kitText);
         const kitDir = path.basename(kitRef) === "kit.json" ? path.dirname(kitRef) : kitRef;
         reporter.check(fs.existsSync(kitDir) && fs.statSync(kitDir).isDirectory(), `${rel(kitsCatalogPath)}: kits[${index}] points at missing kit folder: ${kitText}`);
-        validateKitRepository(kitDir, reporter);
-    });
+        await validateKitRepository(kitDir, reporter);
+    }
 }
 function validateAgentPaths(reporter, manifest) {
     for (const file of walkFiles(path.join(root, "agents")).filter((item) => item.endsWith(".json"))) {
@@ -480,6 +334,32 @@ function validatePublicScriptWrappers(reporter) {
         reporter.check(JSON.stringify(significantLines) === JSON.stringify(policy.significantLines), `${file}: public wrapper must match the exact thin launcher body for ${policy.target}`);
     }
 }
+function validateAdrNumbers(reporter) {
+    // Each ADR (a docs/adr file with an `# ADR NNNN:` heading) must own a unique
+    // number, and its filename prefix must match that number. Companion/index docs
+    // without an ADR heading (e.g. a numbered skill-audit tied to an ADR) are
+    // intentionally skipped. Guards against concurrent number collisions like the
+    // duplicate ADR 0014 from PRs #180/#172.
+    const adrDir = path.join(root, "docs/adr");
+    if (!fs.existsSync(adrDir))
+        return;
+    const byNumber = new Map();
+    for (const file of walkFiles(adrDir)) {
+        if (path.extname(file) !== ".md")
+            continue;
+        const heading = readText(file).match(/^#\s+ADR\s+(\d{4}):/m);
+        if (!heading)
+            continue; // not an ADR decision doc
+        const num = heading[1];
+        reporter.check(path.basename(file).startsWith(`${num}-`), `${rel(file)}: ADR heading number ${num} does not match the filename prefix`);
+        const list = byNumber.get(num) ?? [];
+        list.push(rel(file));
+        byNumber.set(num, list);
+    }
+    for (const [num, files] of byNumber) {
+        reporter.check(files.length === 1, `docs/adr: duplicate ADR number ${num} — ${files.join(", ")}. ADR numbers must be unique; renumber one.`);
+    }
+}
 function validateHookInventory(reporter) {
     const readme = readText(path.join(root, "scripts/README.md"));
     const hookFiles = walkFiles(path.join(root, "scripts/hooks"))
@@ -605,7 +485,7 @@ function validateNoFirstPartyPythonCommands(reporter) {
         reporter.fail(`${relative}: direct first-party Python command reference is not allowed; use npm/flow-agents TypeScript commands`);
     }
 }
-export function main(argv = process.argv.slice(2)) {
+export async function main(argv = process.argv.slice(2)) {
     const kitIndex = argv.indexOf("--kit");
     if (kitIndex >= 0) {
         const kitDir = argv[kitIndex + 1];
@@ -619,7 +499,7 @@ export function main(argv = process.argv.slice(2)) {
             console.log(`info: validating kit Flow Definitions with Flow CLI at ${localCli}`);
         else
             console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
-        validateKitRepository(path.resolve(kitDir), reporter);
+        await validateKitRepository(path.resolve(kitDir), reporter);
         if (reporter.errors.length) {
             console.log("Flow Kit repository validation failed:");
             for (const error of reporter.errors)
@@ -635,14 +515,14 @@ export function main(argv = process.argv.slice(2)) {
     validateAgentCards(reporter, agentNames);
     validatePowers(reporter);
     validateManifest(reporter, manifest, agentNames);
-    validatePacksManifest(reporter, agentNames);
-    validateKits(reporter);
+    await validateKits(reporter);
     validateAgentPaths(reporter, manifest);
     validateLegacyRefs(reporter);
     validateMirrors(reporter);
     validateUsageFeedbackFiles(reporter);
     validatePublicScriptWrappers(reporter);
     validateHookInventory(reporter);
+    validateAdrNumbers(reporter);
     validateFixtureOwnership(reporter);
     validatePackageCommandSurface(reporter);
     validateNoFirstPartyPythonFiles(reporter);
@@ -672,5 +552,5 @@ catch {
     return process.argv[1];
 } })();
 if (_selfRealPath === _argv1RealPath) {
-    process.exitCode = main();
+    main().then((code) => { process.exitCode = code; });
 }

package/context/contracts/artifact-contract.md

@@ -20,6 +20,16 @@ The artifact root is local working memory unless a workflow explicitly promotes
 - Do not commit local workflow runtime roots such as `.flow-agents/<slug>/` as durable policy unless a repository-specific contract explicitly says that artifact is promoted.
 - Do not commit local workflow runtime roots such as `.flow-agents/<slug>/`; final acceptance must promote durable content before merge.
 
+## Persistence Integrity
+
+Writing a durable artifact must **fail loud, never fail-open.** If a record (state, evidence, a
+trust.bundle, a claim) cannot be persisted — a missing dependency, a validation failure, an I/O
+error — the operation **fails with the reason**; it must not return success while silently
+dropping the write. A silently-skipped persist is **data loss**, not a degraded mode, and is
+invisible to the caller that depended on it. Callers act on persistence **return values**, not
+just thrown exceptions. (See #160: an ignored `{written:false}` from the bundle writer dropped
+records under concurrency.)
+
 ## Required Artifact Types
 
 ### Structured Sidecars

package/context/contracts/delivery-contract.md

@@ -61,6 +61,7 @@ After CI passes and the work is merged, released, or otherwise accepted:
 - [ ] durable docs link back to the provider record, archived plan, or session artifact when useful
 - [ ] local `.flow-agents/` runtime artifacts remain untracked, and durable outcomes are promoted before merge to `main`
 - [ ] follow-up issues or learning-review items created for deferred work
+- [ ] **workspace cleaned up after a confirmed merge**: the merge is verified from the provider's own merge record (a merge commit / `mergedAt`), not a green check or a command exit code; then the isolated worktree is removed and the now-merged branch is deleted locally and on the remote, honoring the `worktree_lifecycle` (`retain_until: pr_merged`) recorded at selection. Never delete a branch or worktree before the merge is confirmed. A delivery is not complete while it leaves a stale worktree or merged branch behind.
 
 ## Distribution Rule
 

package/context/contracts/review-contract.md

@@ -59,6 +59,7 @@ All reviewers are read-only reporters. They may inspect files, run read-only ana
 Attempt relevant perspectives and record findings:
 
 - Code quality: readability, naming, function/file size, error handling, duplication, maintainability
+- Failure handling: callers act on failure *return values*, not just exceptions — flag fail-open on any data-persisting path (per the persistence-integrity invariant in the artifact contract)
 - Correctness risks: edge cases, unintended behavior, unsafe assumptions, missing tests
 - Standards fit: project conventions, local architecture, public contracts, documented decisions
 - Security: secrets, injection, XSS, path traversal, auth/authz, unsafe external calls, vulnerable dependencies

package/context/contracts/verification-contract.md

@@ -29,6 +29,8 @@ Attempt relevant phases and record evidence:
 
 If a tool or environment is unavailable, mark that phase `NOT_VERIFIED` with the reason. Do not skip silently.
 
+A flaky or intermittently-failing test is a real defect — a race, a fail-open, or nondeterminism — not noise. Root-cause it; never re-run to green or mark it `skip`/`pass` to move on. An operation that can pass without doing its job is a failure, not a flake.
+
 Provider-check gaps are risk-based:
 
 - Docs-only changes may use `SKIP` / `skip` for missing provider checks only when the report names the skipped check, explains why local docs evidence is enough, and the repository does not require the missing check.

package/context/gate-awareness.md

@@ -0,0 +1,39 @@
+# Gate Awareness
+
+This repo runs three active gates implemented as Claude Code hook scripts. Every agent working here should know when each gate fires, what it checks, and what the correct posture is when a gate blocks or when a suspected block does not appear.
+
+## Active Gates
+
+**goal-fit/Stop** (`scripts/hooks/stop-goal-fit.js`): fires on the agent Stop event (before the agent final-answers as complete). The gate reads `.flow-agents/` to find the most recent active workflow artifact and checks for: an incomplete Definition Of Done section, an incomplete or absent Goal Fit Gate section, open items in Final Acceptance when status is delivered, failing or NOT_VERIFIED checks in `evidence.json`, open sidecar issues (state.json showing non-done status, critique.json with open findings), and evidence cross-reference failures (the capture log in `command-log.jsonl` contradicting a claimed-pass command check in `evidence.json`). In `block` mode the gate exits 2, which prevents the Stop. The canonical engine default is `warn` (exit 0 with guidance on stderr); shipped runtime configs such as Claude Code at L2 set `block` so the installed product enforces. The gate releases automatically after a configurable number of consecutive identical blocks (default 3) to surface the situation to the human rather than looping forever.
+
+**evidence-capture** (`scripts/hooks/evidence-capture.js`): fires as a postToolUse hook on every shell or command tool execution. It deterministically records the actual command result — not the model's narration about it — to `.flow-agents/<slug>/command-log.jsonl` as an append-only JSONL log. Each record captures the command string, observed result (pass/fail), exit code when available, and a timestamp. Non-blocking; always exits 0. Fail-open: a capture failure never blocks the agent or corrupts the log.
+
+**reground** (`scripts/hooks/workflow-steering.js`): fires on `SessionStart` and `UserPromptSubmit` to re-inject the active workflow phase, goal, and next-step from `state.json` into the agent turn. This is what keeps an in-flight goal alive through context compaction and session resume without requiring the agent to voluntarily re-read sidecars. The hook also fires after subagent calls (use_subagent) to inject phase-transition reminders tailored to the completing subagent (planner, worker, reviewer, verifier). Non-blocking; always exits 0.
+
+## A Block Is The System Working
+
+When the goal-fit/Stop gate blocks, that is the system functioning correctly, not an obstacle to route around. The gate blocked because it found a genuine gap: an open Definition Of Done item, a failed evidence check, a sidecar showing non-done status, or a command the capture log shows actually failed while the evidence claims it passed. Routing around the block, silencing the hook, or suppressing the exit code treats a functioning quality gate as an error to ignore. It is not. Address the gap the gate named.
+
+## Judge Gate Correctness
+
+A block demands evaluation, not blind obedience and not blind routing-around. When the goal-fit/Stop gate fires, ask: is this a true-block or a false-block?
+
+A true-block is a case where the gate is correct: a real gap exists — an unchecked Definition Of Done item, a command that genuinely failed, a missing sidecar, an open review finding — and the system is right to prevent delivery until the gap is closed. The correct response to a true-block is to close the gap, then re-attempt.
+
+A false-block is a case where the gate has a genuine bug or is acting on stale or corrupt data — for example, a sidecar that was incorrectly written, a `command-log.jsonl` entry that misrecorded a passing command as a failure due to a capture-hook defect, or a `state.json` that was never updated to `done` even though the work is complete.
+
+The path to a clean pass is always to **produce real evidence**, never to make the proof say what you want: run the command so the capture hook records the real result, finish the missing Definition-of-Done item, write the sidecar the flow forgot. Proof artifacts are not yours to hand-author into a pass — `command-log.jsonl` is owned by the capture hook and must never be hand-edited, and a verdict you write for yourself is not evidence of anything. Correcting a genuinely-wrong artifact is a last resort: do it transparently, note it as a correction, and prefer regenerating it through the tool that owns it. If the only way you can see to clear a block is to edit the proof, that is the signal to stop and surface the situation, not to proceed.
+
+Do not conflate "inconvenient" with "false-block." If the gap named by the gate is real, it is a true-block regardless of how close to done the work feels.
+
+## Missed-Block Diagnostic
+
+When a gate does not fire and you suspect it should have, the gate is almost never defective. The goal-fit/Stop gate only knows what the flow recorded in `.flow-agents/<slug>/`. It cross-references `evidence.json` command checks against `command-log.jsonl`. A suspected missed block nearly always means the flow did not record the evidence, not that the gate failed to evaluate it.
+
+Start diagnosis here:
+
+1. Check `.flow-agents/<slug>/command-log.jsonl` — was the relevant command captured? If the evidence-capture hook was not active when the command ran (for example, the session predated the hook or the artifact directory was not yet resolved), the log will have no entry for that command and the Stop gate will see no contradiction to raise.
+2. Check `.flow-agents/<slug>/evidence.json` — does the relevant check exist with kind `command` and status `pass`? The gate only cross-references checks that are explicitly recorded in `evidence.json` as command-kind claimed passes. If the check was never written there, the gate has nothing to cross-reference.
+3. If both files are present and consistent but the block still did not fire, verify that the artifact directory the gate found is the one you expect (`state.json` newest-mtime resolution) and that the workflow artifact has the correct type and status to be treated as active.
+
+A gate defect is a last resort diagnosis, not a first assumption.