@mrciphersmith/keryx 0.2.69 → 0.2.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.69",
+  "version": "0.2.70",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdgraph/build-lang.test.ts

@@ -188,6 +188,13 @@ test("buildGraph resolves Python absolute, relative, and __init__.py imports", a
 // !!! NEVER regenerate these goldens to make a diff disappear. If this test
 // !!! fails, the TS/JS code path changed and AC4 is violated — fix the code,
 // !!! not the golden.
+//
+// EXCEPTION, recorded rather than silently applied: flow 140 (P1 — dynamic
+// imports counted as load-order cycles) intentionally adds an `importKind`
+// field to every edge record, TS/JS included — the whole point of that flow
+// is that the field was missing. That is a deliberate schema change, not a
+// TS/JS behavior drift from Java/Python work, so the AC4 invariant above
+// still holds; only the pinned literal needed the new field appended.
 // ---------------------------------------------------------------------------
 
 const GOLDEN_NODES_JSONL =
@@ -197,9 +204,9 @@ const GOLDEN_NODES_JSONL =
   `{"id":"src/feature/value.ts","kind":"file","path":"src/feature/value.ts","language":"typescript"}\n`;
 
 const GOLDEN_EDGES_JSONL =
-  `{"id":"edge:1","from":"src/feature/helper.js","to":"src/feature/value.ts","kind":"imports","specifier":"./value"}\n` +
-  `{"id":"edge:2","from":"src/feature/index.ts","to":"src/feature/style.css","kind":"asset","specifier":"./style.css"}\n` +
-  `{"id":"edge:3","from":"src/feature/index.ts","to":"src/feature/value.ts","kind":"imports","specifier":"./value"}\n`;
+  `{"id":"edge:1","from":"src/feature/helper.js","to":"src/feature/value.ts","kind":"imports","specifier":"./value","importKind":"import-statement"}\n` +
+  `{"id":"edge:2","from":"src/feature/index.ts","to":"src/feature/style.css","kind":"asset","specifier":"./style.css","importKind":"import-statement"}\n` +
+  `{"id":"edge:3","from":"src/feature/index.ts","to":"src/feature/value.ts","kind":"imports","specifier":"./value","importKind":"import-statement"}\n`;
 
 test("buildGraph output is byte-identical for a TS/JS-only project (AC4 guard)", async () => {
   const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-lang-regression");

package/src/gdgraph/build.ts

@@ -1,7 +1,8 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import type { GraphData, GraphEdge, GraphNode } from "./types";
+import type { GraphData, GraphEdge, GraphNode, ImportKind, TranspilerImportKind } from "./types";
+import { UNKNOWN_IMPORT_KIND } from "./types";
 
 const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".java", ".py"];
 const SOURCE_RESOLUTION_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".d.ts", ".java", ".py"];
@@ -111,9 +112,9 @@ export async function buildGraph(projectRoot: string): Promise<BuildResult> {
     // dropped), so the resolution metric is honest. TS/JS keeps the exact
     // original guard (relative + tsconfig alias only) ⇒ byte-identical output.
     const isLanguageAware = language === "java" || language === "python";
-    const specifiers = extractImportSpecifiers(content, language);
+    const records = extractImportRecords(content, language);
 
-    for (const specifier of specifiers) {
+    for (const { specifier, kind: importKind } of records) {
       const resolved = resolveImport(projectRoot, file, specifier, fileSet, resolver);
       const asset = resolved ? null : resolveAssetImport(projectRoot, file, specifier, resolver);
       const shouldTrackUnresolved =
@@ -136,6 +137,7 @@ export async function buildGraph(projectRoot: string): Promise<BuildResult> {
         to: resolved ?? asset ?? specifier,
         kind: resolved ? "imports" : asset ? "asset" : "unresolved",
         specifier,
+        importKind,
       });
     }
   }
@@ -200,14 +202,27 @@ async function collectSourceFiles(projectRoot: string): Promise<SourceCollection
   return { files: result.sort(), skippedDirectories: skippedDirectories.sort() };
 }
 
-function extractImportSpecifiers(content: string, language: string): string[] {
+type ImportRecord = { specifier: string; kind: ImportKind };
+
+// P1 remediation (flow 140): union the transpiler and fallback extractors as
+// before, but keep the transpiler's per-specifier kind alive instead of
+// collapsing everything to a bare specifier string. `build()`'s edge-writing
+// loop reads `record.kind` straight onto the edge, so cycle detection can
+// later tell a load-order `import-statement` from a call-time `dynamic-import`
+// instead of the previous single "imports" bucket.
+function extractImportRecords(content: string, language: string): ImportRecord[] {
   // Java/Python are not TS/JS syntax — the tsx transpiler cannot scan them
   // (it throws today, which is why they already reach the fallback). Route them
   // explicitly to the regex fallback that carries the java/python patterns,
   // rather than depending on the transpiler always throwing. TS/JS keep the
   // exact original transpiler-then-fallback path ⇒ byte-identical output.
+  // The fallback is a plain regex with no notion of import kind, so every
+  // Java/Python edge is marked UNKNOWN_IMPORT_KIND — never guessed (AC4).
   if (language === "java" || language === "python") {
-    return extractImportSpecifiersFallback(content);
+    return extractImportSpecifiersFallback(content).map((specifier) => ({
+      specifier,
+      kind: UNKNOWN_IMPORT_KIND,
+    }));
   }
   // `Bun.Transpiler#scanImports` ERASES type-only imports: `import type {X} from
   // "./m"` and `export type {X} from "./m"` are compiled away, so the transpiler
@@ -219,16 +234,46 @@ function extractImportSpecifiers(content: string, language: string): string[] {
   // odd formatting), the fallback contributes the type-only ones.
   const scanned = scanImportsOrEmpty(content);
   const fallback = extractImportSpecifiersFallback(content);
-  return [...new Set([...scanned, ...fallback])].sort();
+
+  const kindBySpecifier = new Map<string, ImportKind>();
+  for (const { specifier, kind } of scanned) {
+    const existing = kindBySpecifier.get(specifier);
+    // The same specifier can appear more than once in a file (a static import
+    // plus a separate `await import()` of the same path). A real static edge
+    // makes it a load-order dependency regardless of what else also imports
+    // it dynamically elsewhere in the file, so a non-dynamic kind always wins
+    // over a dynamic one already recorded for the same specifier.
+    if (!existing || (existing === "dynamic-import" && kind !== "dynamic-import")) {
+      kindBySpecifier.set(specifier, kind);
+    }
+  }
+  // Fallback-only specifiers (not seen by the transpiler at all — e.g.
+  // type-only imports) get the explicit unknown/static marker, never a
+  // guessed kind (AC4). A specifier the transpiler DID see keeps its real
+  // kind; the fallback never overrides it.
+  for (const specifier of fallback) {
+    if (!kindBySpecifier.has(specifier)) {
+      kindBySpecifier.set(specifier, UNKNOWN_IMPORT_KIND);
+    }
+  }
+
+  return [...kindBySpecifier.entries()]
+    .map(([specifier, kind]) => ({ specifier, kind }))
+    .sort((a, b) => a.specifier.localeCompare(b.specifier));
 }
 
-function scanImportsOrEmpty(content: string): string[] {
+type ScannedImport = { specifier: string; kind: TranspilerImportKind };
+
+function scanImportsOrEmpty(content: string): ScannedImport[] {
   try {
     const scanner = new Bun.Transpiler({ loader: "tsx" });
     return scanner
       .scanImports(content)
-      .map((entry) => entry.path)
-      .filter((specifier): specifier is string => typeof specifier === "string" && specifier.length > 0);
+      .filter(
+        (entry): entry is { path: string; kind: TranspilerImportKind } =>
+          typeof entry.path === "string" && entry.path.length > 0,
+      )
+      .map((entry) => ({ specifier: entry.path, kind: entry.kind }));
   } catch {
     // Unparseable source ⇒ the regex fallback alone still yields the imports.
     return [];

package/src/gdgraph/import-kind.test.ts

@@ -0,0 +1,205 @@
+// P1 remediation (flow 140) — `keryx gdgraph query cycles` was folding
+// `await import()` edges into the load-order cycle count. `Bun.Transpiler
+// #scanImports` already reports whether a specifier is a static
+// import-statement, a dynamic-import, a require-call, etc.; `build.ts` threw
+// that classification away one line after receiving it. These tests are
+// written FIRST (TDD RED) against the frozen acceptance criteria in
+// `.metaproject/flows/140-2026-08-07-gdgraph-dynamic-import-edges/acceptance-criteria.md`.
+//
+// Conventions mirror build.test.ts / build-lang.test.ts: uniqueTestRoot(),
+// reset(root), buildGraph(root), loadGraph(root).
+
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "bun:test";
+import { buildGraph } from "./build";
+import { getCycles, loadGraph } from "./query";
+import { uniqueTestRoot } from "../lib/test-tmp";
+
+async function reset(root: string): Promise<void> {
+  await rm(root, { recursive: true, force: true });
+  await mkdir(root, { recursive: true });
+}
+
+// ---------------------------------------------------------------------------
+// AC1 — every edge the transpiler produced carries the kind scanImports
+// actually returned, and it survives to the written edge record.
+// ---------------------------------------------------------------------------
+
+test("AC1 — the transpiler's import kind survives onto the written edge record", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-import-kind-ac1");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "index.ts"),
+    [
+      "import { staticValue } from './static';",
+      "const loadDynamic = async () => { const { dynamicValue } = await import('./dynamic'); return dynamicValue; };",
+      "const required = require('./required');",
+      "export const result = { staticValue, loadDynamic, required };",
+      "",
+    ].join("\n"),
+  );
+  await writeFile(path.join(root, "src", "static.ts"), "export const staticValue = 1;\n");
+  await writeFile(path.join(root, "src", "dynamic.ts"), "export const dynamicValue = 2;\n");
+  await writeFile(path.join(root, "src", "required.ts"), "export const requiredValue = 3;\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edgesFromIndex = graph.edges.filter(
+    (edge) => edge.from === "src/index.ts" && edge.kind === "imports",
+  );
+  const importKindByTarget = new Map(edgesFromIndex.map((edge) => [edge.to, edge.importKind]));
+
+  expect(importKindByTarget.get("src/static.ts")).toBe("import-statement");
+  expect(importKindByTarget.get("src/dynamic.ts")).toBe("dynamic-import");
+  expect(importKindByTarget.get("src/required.ts")).toBe("require-call");
+});
+
+test("a specifier imported both statically and dynamically in the same file keeps the static classification", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-import-kind-mixed-specifier");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "index.ts"),
+    [
+      "import './shared';",
+      "const loadAgain = async () => { await import('./shared'); };",
+      "export const result = loadAgain;",
+      "",
+    ].join("\n"),
+  );
+  await writeFile(path.join(root, "src", "shared.ts"), "export const shared = true;\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find((item) => item.from === "src/index.ts" && item.to === "src/shared.ts");
+
+  expect(edge?.importKind).toBe("import-statement");
+});
+
+// ---------------------------------------------------------------------------
+// AC2 — a fixture reproducing the target's shape: one static edge, one
+// dynamic-import edge back, no longer reported as a load-order cycle.
+// ---------------------------------------------------------------------------
+
+test("AC2 — a cycle closed only through a dynamic-import edge is no longer reported as load-order", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-cycle-mixed");
+  await reset(root);
+  await mkdir(path.join(root, "bot", "commands"), { recursive: true });
+  // Mirrors the target's shape: commands/menu.ts statically imports
+  // callbacks.ts; callbacks.ts reaches back into menu.ts only via `await
+  // import()`.
+  await writeFile(
+    path.join(root, "bot", "commands", "menu.ts"),
+    "import { registerCallback } from '../callbacks';\nexport const menu = () => registerCallback();\n",
+  );
+  await writeFile(
+    path.join(root, "bot", "callbacks.ts"),
+    [
+      "export const registerCallback = () => 1;",
+      "export const handleMenuCallback = async () => {",
+      "  const { menu } = await import('./commands/menu');",
+      "  return menu();",
+      "};",
+      "",
+    ].join("\n"),
+  );
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const cycles = getCycles(graph);
+
+  expect(
+    cycles.some((cycle) => cycle.includes("bot/callbacks.ts") && cycle.includes("bot/commands/menu.ts")),
+  ).toBe(false);
+});
+
+// ---------------------------------------------------------------------------
+// AC3 — classification both ways, same two-file cycle shape.
+// ---------------------------------------------------------------------------
+
+test("AC3 — a two-file cycle formed by static imports IS reported", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-cycle-static");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(path.join(root, "src", "a.ts"), "import { b } from './b';\nexport const a = () => b();\n");
+  await writeFile(path.join(root, "src", "b.ts"), "import { a } from './a';\nexport const b = () => a();\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const cycles = getCycles(graph);
+
+  expect(cycles.some((cycle) => cycle.includes("src/a.ts") && cycle.includes("src/b.ts"))).toBe(true);
+});
+
+test("AC3 — the same two-file cycle formed by await import() is NOT reported as load-order", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-cycle-dynamic");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "a.ts"),
+    "export const a = async () => { const { b } = await import('./b'); return b(); };\n",
+  );
+  await writeFile(
+    path.join(root, "src", "b.ts"),
+    "export const b = async () => { const { a } = await import('./a'); return a(); };\n",
+  );
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const cycles = getCycles(graph);
+
+  expect(cycles.some((cycle) => cycle.includes("src/a.ts") && cycle.includes("src/b.ts"))).toBe(false);
+});
+
+// ---------------------------------------------------------------------------
+// AC4 — an edge found only by the regex fallback (never seen by scanImports)
+// is marked with an explicit unknown/static marker, never inferred dynamic.
+// A type-only import is the real-world case: `Bun.Transpiler#scanImports`
+// erases `import type {...}` entirely, so it reaches the graph only through
+// `extractImportSpecifiersFallback`.
+// ---------------------------------------------------------------------------
+
+test("AC4 — a fallback-only edge (type-only import) is marked unknown-static, never inferred dynamic", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-import-kind-ac4");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "consumer.ts"),
+    "import type { Shape } from './types';\nexport const consumer: Shape = { ok: true } as Shape;\n",
+  );
+  await writeFile(path.join(root, "src", "types.ts"), "export interface Shape { ok: boolean }\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find((item) => item.from === "src/consumer.ts" && item.to === "src/types.ts");
+
+  expect(edge).toBeDefined();
+  expect(edge?.importKind).toBe("unknown-static");
+  expect(edge?.importKind).not.toBe("dynamic-import");
+});
+
+test("AC4 — Java imports (fallback-only language) are marked unknown-static, never dynamic", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-import-kind-java");
+  await reset(root);
+  const javaRoot = path.join(root, "src", "main", "java", "com", "example");
+  await mkdir(javaRoot, { recursive: true });
+  await writeFile(
+    path.join(javaRoot, "Consumer.java"),
+    "package com.example;\nimport com.example.Model;\npublic class Consumer {}\n",
+  );
+  await writeFile(path.join(javaRoot, "Model.java"), "package com.example;\npublic class Model {}\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find(
+    (item) =>
+      item.from === "src/main/java/com/example/Consumer.java" &&
+      item.to === "src/main/java/com/example/Model.java",
+  );
+
+  expect(edge).toBeDefined();
+  expect(edge?.importKind).toBe("unknown-static");
+});

package/src/gdgraph/query.ts

@@ -61,7 +61,12 @@ export function getCycles(graph: GraphData): string[][] {
     adjacency.set(node.path, []);
   }
   for (const edge of graph.edges) {
-    if (edge.kind !== "imports") {
+    // A `dynamic-import` (`await import()`) resolves at call time, not
+    // module-load time, so a cycle closed only through one is not the
+    // load-order cycle this query answers (P1, flow 140). Excluding it here
+    // — rather than reclassifying `edge.kind` — leaves orphans/affected
+    // untouched (AC5): both still treat the edge as a normal import.
+    if (edge.kind !== "imports" || edge.importKind === "dynamic-import") {
       continue;
     }
     adjacency.get(edge.from)?.push(edge.to);

package/src/gdgraph/types.ts

@@ -5,12 +5,46 @@ export type GraphNode = {
   language: "typescript" | "javascript" | "java" | "python" | "asset";
 };
 
+// Import classification straight from `Bun.Transpiler#scanImports` (P1
+// remediation, flow 140). A static `import`/`export ... from` statement is a
+// load-order dependency; `dynamic-import` (`await import()`) resolves at call
+// time and is not. The full union mirrors every literal `scanImports` can
+// return (bun-types `ImportKind`), so a transpiler-found edge always carries
+// the value the transpiler actually reported — never a guess.
+export type TranspilerImportKind =
+  | "import-statement"
+  | "require-call"
+  | "require-resolve"
+  | "dynamic-import"
+  | "import-rule"
+  | "url-token"
+  | "internal"
+  | "entry-point-run"
+  | "entry-point-build";
+
+// A specifier found ONLY by the regex fallback (`extractImportSpecifiersFallback`
+// in build.ts) carries no real kind from the transpiler — the fallback is a
+// plain regex with no notion of "static" vs "dynamic". Never infer one;
+// `UNKNOWN_IMPORT_KIND` marks it explicitly and cycle detection treats it as
+// load-order (the pre-fix behavior), so fallback-only edges are never
+// silently excluded from a real cycle.
+export const UNKNOWN_IMPORT_KIND = "unknown-static" as const;
+
+export type ImportKind = TranspilerImportKind | typeof UNKNOWN_IMPORT_KIND;
+
 export type GraphEdge = {
   id: string;
   from: string;
   to: string;
   kind: "imports" | "asset" | "unresolved";
   specifier: string;
+  // Provenance/kind of the specifier that produced this edge (P1, flow 140).
+  // `buildGraph()` always sets this. Optional (not required) so edge literals
+  // constructed before this field existed — test fixtures elsewhere in the
+  // repo, or graphs persisted by an older `keryx gdgraph build` — stay valid;
+  // `getCycles` treats a missing value as load-order, matching pre-fix
+  // behavior rather than crashing or silently mis-classifying.
+  importKind?: ImportKind;
 };
 
 export type GraphData = {

package/src/gdskills/bundled/rules/core/subagent-status-protocol.md

@@ -32,7 +32,11 @@ If the first line is not `STATUS: <STATUS>`, the orchestrator MUST treat the res
 
 ---
 
-## The Four Statuses
+## The Five Statuses
+
+Four of them are for **skill workers** — the subagents an orchestrator dispatches
+from `.metaproject/skills/`. The fifth, `FAILED`, belongs to a different worker
+family and is documented at the end of this section.
 
 ### `DONE`
 Task fully complete. All acceptance criteria met. Orchestrator can continue the pipeline.
@@ -66,6 +70,28 @@ Use when:
 - The task references files or components that don't exist and no context explains them
 - Acceptance criteria use terms not defined anywhere in the provided context
 
+### `FAILED` — harness child workers only
+
+**Do not emit `FAILED` as a skill worker.** A skill worker that cannot finish
+reports `BLOCKED`; `task-implementer` maps its own internal `failed` to
+`STATUS: BLOCKED` for exactly this reason.
+
+`FAILED` exists in `subagent-result.schema.json` because a **different** worker
+family uses it: external child processes launched through the harness. Their
+`STATUS:` line is parsed by `parseChildResult` in `src/harness/child/contract.ts`
+— which mirrors this enum as `CanonicalSubagentStatus` — and is wired into
+production at `src/harness/extension/execute.ts`. `spawn.test.ts` pins the
+behaviour it guarantees: a `FAILED` child disposition must reach the parent's
+gate as a *failed* completion, **never as a false `completed`**.
+
+So the enum has five values and this document previously described four, which
+made `FAILED` look unreachable. It is not. It is unreachable *from a skill
+worker*, and load-bearing for the child-process layer.
+
+Orchestrators dispatching skill workers may therefore treat a `FAILED` reply as
+a protocol violation and re-request. Orchestrators reading harness child results
+must handle it as a real terminal failure.
+
 ---
 
 ## Exact Response Formats

package/src/gdskills/bundled/skills/orchestration/flow-orchestrator/SKILL.md

@@ -12,7 +12,7 @@ triggers:
   - "managed implementation"
 metadata:
   author: "MrCipherSmith"
-  version: "1.2.0"
+  version: "1.3.0"
   category: "orchestration"
 license: "MIT"
 compatibility: "cursor,codex,zed,opencode,claude"
@@ -54,9 +54,10 @@ Flow state lives in `.metaproject/flows/<flow-id>/`.
 
 CLI-owned files:
 
-- `flow.json` - never edit by hand.
+- `flow.json` - never edit by hand (read it freely; write only via the CLI).
 - status transitions - only through `keryx flow ...`.
 - task status - only through `keryx flow task done ...`.
+- task attempt counts - only through `keryx flow task attempt ...`.
 - frozen acceptance criteria changes - only through
   `keryx flow ac update <id> --reason "<why>"`.
 
@@ -96,7 +97,57 @@ flowchart TD
 
 ## Phase 0: Route And Resume
 
-1. Run `keryx flow list`.
+### 0.0 State Resumption Check
+
+The input contract accepts `mode: "resume"`; this is the procedure behind it.
+Run it before asking the user anything, on **every** invocation — not only when
+`mode` is `resume`. A session that restarts mid-flow remembers nothing of what
+it already tried. The flow package does.
+
+1. Run `keryx flow list`. Any flow whose status is `in-progress`,
+   `implemented`, `completing`, or `blocked` is an interrupted flow.
+2. If one exists, ASK the user, with the concrete numbers, once:
+   "Found an in-flight flow `<id>` '<title>' (status `<status>`, tasks
+   `<done>/<total>`). Resume it, or start a new flow?" Never guess.
+3. If resume:
+   1. Run `keryx flow status <id>` and read the flow package —
+      `description.md`, `plan.md`, `context.md`, `journal.md`, and the frozen
+      `acceptance-criteria.md`.
+   2. Read `.metaproject/flows/<dir>/flow.json` (read-only; it stays CLI-owned)
+      and take `tasks[].attempts.count` and `tasks[].attempts.log` for every
+      task that is not `done`. **That is the attempt count. Never count
+      attempts from your own context** — a resumed session's context starts at
+      zero while the real count does not, and a loop bound computed from zero
+      is not a bound.
+   3. Resume at the first task whose `status` is not `done`, respecting
+      `dependsOn` order.
+   4. Before dispatching a worker for that task, record the attempt:
+
+      ```bash
+      keryx flow task attempt <id> <Tn> --outcome started --detail "resumed after session restart"
+      ```
+
+   5. Apply the Phase 4 attempt budget against the **persisted** count. If
+      `attempts.count` for the task has already reached six, do not re-dispatch
+      the same approach: go to the re-planning step (Phase 4, PR review/fix
+      loop, step 4) and record the decision in `journal.md`.
+   6. If the flow is `blocked`, read the blocking reason from `journal.md`,
+      resolve or escalate it, then `keryx flow unblock <id>`.
+4. If the user wants a new flow, continue at 0.1.
+
+Record attempts as they happen, not only on resume:
+
+```bash
+keryx flow task attempt <id> <Tn> --outcome started|failed|blocked [--detail "<what happened>"]
+```
+
+`attempts.count` is append-only and lives in `flow.json`. A counter that lives
+only in the orchestrator's context resets to zero exactly when the loop bound
+matters most, which makes it not a counter.
+
+### 0.1 Route
+
+1. Reuse the `keryx flow list` output from 0.0.
 2. If an active flow obviously matches the user request, use it.
 3. If multiple active flows could match, ask one concise question.
 4. If no flow exists and the request is multi-step, create one:
@@ -169,10 +220,28 @@ agree at all - the change could not work in production. The check had been
 identified correctly and then skipped, because nothing made skipping it
 visible.
 
-Tasks are the mechanism that already exists for this: `flow complete` gates
-on them, so an unrun verification step keeps the flow open instead of being
+Tasks are the mechanism for this. `keryx flow complete` runs a `tasks` gate
+over them, so an unrun verification step keeps the flow open instead of being
 quietly dropped.
 
+Know the gate's exact scope, because for years this file claimed a gate that
+did not exist and 24 completed flows shipped with an open task:
+
+- the gate is **opt-in per flow package**, keyed on `gates.tasks` in
+  `flow.json`, which `keryx flow init` writes for every flow it creates. A
+  package created before the gate landed does not carry the flag, and for it
+  the gate reports `skipped` and blocks nothing;
+- a task fails the gate when its status is not `done`, when its disposition is
+  `failed`, or when its disposition is `skipped` with no recorded reason;
+- to close a task as deliberately not needed, record why:
+
+  ```bash
+  keryx flow task done <id> <Tn> --disposition skipped --reason "<why it was not needed>"
+  ```
+
+Read the `tasks` line in the `flow complete` output. If it says `skipped`, the
+gate did not run and the task list is yours to verify by hand.
+
 Then freeze and start:
 
 ```bash
@@ -258,9 +327,17 @@ properly formatted `subagent-result`.
 | `DONE_WITH_CONCERNS` | Accept, record every concern in `journal.md`, decide continue vs. add a fix task, then `flow task done`. Never silently drop concerns. |
 | `NEEDS_CONTEXT` | Do not fail. Enrich `context_refs`/`files_to_read` from gdgraph/gdctx/wiki/memory, then re-dispatch the same `dispatch_id`. |
 | `BLOCKED` | `keryx flow block <id> --reason "<worker reason>"`; resolve or escalate one concise question, then `flow unblock` and re-dispatch. |
-| `FAILED` | Retry once with the same dispatch. If it fails again, block the flow and surface the error to the user. |
+| `FAILED` | Emitted by harness **child** workers (`src/harness/child/contract.ts`), never by skill workers — `task-implementer` maps its own `failed` onto `BLOCKED`. Retry once with the same dispatch. If it fails again, block the flow and surface the error to the user. |
 
-Carry `run_id`/`dispatch_id` across retries so the flow journal stays traceable.
+Carry `run_id`/`dispatch_id` across retries so the flow journal stays traceable,
+and record every dispatch against the task's persisted counter so a session
+restart does not reset the budget:
+
+```bash
+keryx flow task attempt <id> <Tn> --outcome started --detail "<dispatch_id>"
+# on a BLOCKED or unusable reply, before re-dispatching:
+keryx flow task attempt <id> <Tn> --outcome blocked --detail "<worker reason>"
+```
 
 ## Phase 3: Verification And Review
 
@@ -316,7 +393,10 @@ How should this flow end?
 2. If findings or required check failures remain, create or update a flow fix
    task, dispatch `task-implementer`, push the fix, and run review again.
 3. Allow at most six review/fix attempts for the current approach. Count an
-   attempt when review/check results are available, including a clean result.
+   attempt when review/check results are available, including a clean result,
+   and record it with `keryx flow task attempt <id> <Tn> --outcome ...` so the
+   count survives a session restart. Read the budget from that task's
+   `attempts.count` in `flow.json`, never from this session's memory.
 4. If attempt six is not clean, do not blindly repeat the same loop. Enrich
    context from the findings, affected graph, relevant wiki, and
    health/testing artifacts; identify the likely cycle cause; choose a

package/src/gdskills/bundled/skills/orchestration/task-implementer/SKILL.md

@@ -531,7 +531,7 @@ Run task-1 (which creates pipeline.ts) before re-dispatching this task, or provi
 - (nothing — blocked before implementation could start)
 ```
 
-See `rules/core/subagent-status-protocol.md` for full format specification and all four status types.
+See `rules/core/subagent-status-protocol.md` for the full format specification. Four statuses are yours as a skill worker; the fifth, `FAILED`, belongs to harness child workers and you must never emit it — report `BLOCKED` instead.
 
 ---