@mrciphersmith/keryx 0.3.48 → 0.3.51

package/dist/core.js

@@ -23145,6 +23145,7 @@ __export(exports_service2, {
   buildAcKindReport: () => buildAcKindReport,
   classifyAcCriterionNotCheckable: () => classifyAcCriterionNotCheckable,
   classifyNotCheckable: () => classifyNotCheckable,
+  completionFixHint: () => completionFixHint,
   computeAcFacts: () => computeAcFacts,
   confirmPreconditionError: () => confirmPreconditionError,
   createFlowService: () => createFlowService,
@@ -23153,11 +23154,13 @@ __export(exports_service2, {
   extractCriterionTokens: () => extractCriterionTokens,
   factsOnlyVerdict: () => factsOnlyVerdict,
   fencedLines: () => fencedLines,
+  flowDeliveryStatementFrom: () => flowDeliveryStatementFrom,
   flowStatementFrom: () => flowStatementFrom,
   hashDiff: () => hashDiff,
   intentNoteForNewFlow: () => intentNoteForNewFlow,
   isFrozen: () => isFrozen,
   notCheckableVerdict: () => notCheckableVerdict,
+  outcomeBulletsFrom: () => outcomeBulletsFrom,
   parseAcceptanceCriteria: () => parseAcceptanceCriteria,
   parseOutcomeAuthor: () => parseOutcomeAuthor,
   proseOutsideFences: () => proseOutsideFences,
@@ -25860,6 +25863,25 @@ function statementFrom(markdown, headings) {
 function flowStatementFrom(description) {
   return statementFrom(description, FLOW_STATEMENT_HEADINGS);
 }
+function flowDeliveryStatementFrom(description) {
+  return statementFrom(description, [/^expected outcome$/i, /^problem$/i]);
+}
+function outcomeBulletsFrom(markdown) {
+  const body = sectionOf(markdown, /^outcome criteri(?:a|on)$/i);
+  if (body === null)
+    return null;
+  const bullets = [];
+  for (const line of body.split(/\r?\n/)) {
+    const bullet = /^\s*[-*]\s+(.*)$/.exec(line);
+    if ((bullet?.[1] ?? line).trim() === OUTCOME_HINT)
+      continue;
+    if (bullet !== null)
+      bullets.push((bullet[1] ?? "").trim());
+    else if (line.trim().length > 0 && bullets.length > 0)
+      bullets[bullets.length - 1] += ` ${line.trim()}`;
+  }
+  return bullets.filter((bullet) => bullet.length > 0);
+}
 var INIT_INTENT_NOTE = "note: no intent statement extractable from description.md \u2014 the product index will hold no statement for this flow";
 function initIntentNote(description) {
   return flowStatementFrom(description) === null ? INIT_INTENT_NOTE : null;
@@ -26334,6 +26356,63 @@ async function deriveAcKinds(cwd, dir, flowId) {
   const { report } = buildAcKindReport(flowId, await readFile27(acPath(cwd, dir), "utf8"));
   return { ...report.criteria };
 }
+function prMergeState(pr, gates) {
+  switch (pr.kind) {
+    case "no-pr":
+      return { state: "no-pr", detail: "no PR recorded on the flow" };
+    case "merged-commit": {
+      const merge = gates.find((gate) => gate.name === "main-merge");
+      return merge?.status === "pass" ? { state: "merged", detail: `direct merge: ${merge.detail}` } : { state: "unknown", detail: `direct merge not verified: ${merge?.detail ?? "main-merge gate missing"}` };
+    }
+    case "tracker-unavailable":
+      return { state: "unknown", detail: "tracker unavailable (is `gh` installed and authenticated?)" };
+    case "unevaluable":
+      return { state: "unknown", detail: "the tracker call failed" };
+    case "observed": {
+      if (!pr.exists)
+        return { state: "not-found", detail: "the tracker found no such PR" };
+      const state = pr.state?.toUpperCase();
+      if (state === "MERGED")
+        return { state: "merged", detail: "PR merged" };
+      if (state === "OPEN")
+        return { state: "open", detail: "PR open, not merged" };
+      if (state === "CLOSED")
+        return { state: "closed", detail: "PR closed without merging" };
+      return { state: "unknown", detail: pr.state === null ? "the tracker did not report a PR state" : `unrecognised PR state: ${pr.state}` };
+    }
+  }
+}
+var UNCONFIRMED_PREFIX = "unconfirmed: ";
+var NO_PR_DETAIL = "no PR recorded";
+function completionAdmitted(status, merged) {
+  return canTransition(status, "completing") || merged && status === "in-progress";
+}
+function completionFixHint(gate, flowId) {
+  if (gate.status !== "fail")
+    return;
+  switch (gate.name) {
+    case "acceptance-criteria": {
+      const unconfirmed = gate.detail.startsWith(UNCONFIRMED_PREFIX) ? gate.detail.slice(UNCONFIRMED_PREFIX.length).split(", ") : [];
+      const first = unconfirmed[0];
+      if (first === undefined)
+        return;
+      const more = unconfirmed.length > 1 ? ` (then ${unconfirmed.slice(1).join(", ")})` : "";
+      return `keryx flow ac confirm ${flowId} ${first} --note "<evidence>"${more}`;
+    }
+    case "pull-request":
+      return gate.detail === NO_PR_DETAIL ? `keryx flow implemented ${flowId} --pr <url>` : undefined;
+    case "tasks":
+      return `keryx flow next ${flowId}`;
+    case "owner":
+      return `keryx flow owner set ${flowId} --owner "<name>" --reason "<why>"`;
+    case "health":
+      return "keryx health run";
+    case "confirmation":
+      return `keryx flow confirm ${flowId} (in a terminal)`;
+    default:
+      return;
+  }
+}
 function recordAttempt(task, outcome, at, detail) {
   const attempts = task.attempts ?? { count: 0, log: [] };
   attempts.count += 1;
@@ -26393,6 +26472,106 @@ function createFlowService(deps) {
     flow.status = "in-progress";
     return save(cwd, dir, flow, event, detail);
   }
+  async function evaluateCompletionGates(cwd, dir, flow, mergedCommit, confirmToken) {
+    const gates = [];
+    try {
+      await assertAcIntact(cwd, dir, flow);
+      const criteria = await readAcCriteria(cwd, dir);
+      const missing = criteria.filter((criterion) => !flow.acConfirmed[criterion]);
+      gates.push(missing.length === 0 && criteria.length > 0 ? { name: "acceptance-criteria", status: "pass", detail: `${criteria.length} confirmed` } : {
+        name: "acceptance-criteria",
+        status: "fail",
+        detail: criteria.length === 0 ? "no criteria found" : `${UNCONFIRMED_PREFIX}${missing.join(", ")}`
+      });
+    } catch {
+      gates.push(unevaluableGate("acceptance-criteria"));
+    }
+    let confirmationToken;
+    let confirmationOutcome;
+    try {
+      const confirmation = await confirmationGate(cwd, dir, flow, confirmToken, completionTarget({ merged: Boolean(mergedCommit), prUrl: flow.pr.url }), deps.now());
+      confirmationOutcome = confirmation.outcome;
+      confirmationToken = confirmation.stored;
+    } catch {
+      confirmationOutcome = unevaluableGate("confirmation");
+    }
+    let evaluatedHeadCommit = mergedCommit ?? undefined;
+    let pr;
+    if (mergedCommit) {
+      pr = { kind: "merged-commit" };
+      try {
+        const merge = deps.mainMergeGate ? await deps.mainMergeGate(cwd, mergedCommit) : await verifyCommitOnMain(cwd, mergedCommit);
+        gates.push({ name: "main-merge", status: merge.status, detail: merge.detail });
+      } catch {
+        gates.push(unevaluableGate("main-merge"));
+      }
+    } else if (!flow.pr.url) {
+      pr = { kind: "no-pr" };
+      gates.push({ name: "pull-request", status: "fail", detail: NO_PR_DETAIL });
+    } else {
+      pr = { kind: "unevaluable" };
+      try {
+        if (deps.tracker && await deps.tracker.detect()) {
+          const status = await deps.tracker.prStatus(flow.pr.url);
+          pr = { kind: "observed", exists: status.exists, state: status.state ?? null };
+          if (typeof status.headSha === "string" && status.headSha !== "") {
+            evaluatedHeadCommit ??= status.headSha;
+          }
+          gates.push(status.exists && status.checksGreen === true ? { name: "pull-request", status: "pass", detail: "PR exists, checks green" } : {
+            name: "pull-request",
+            status: "fail",
+            detail: !status.exists ? "PR not found" : "PR checks not green"
+          });
+        } else {
+          pr = { kind: "tracker-unavailable" };
+          gates.push({
+            name: "pull-request",
+            status: "skipped",
+            detail: "tracker unavailable; verify PR checks manually"
+          });
+        }
+      } catch {
+        gates.push(unevaluableGate("pull-request"));
+      }
+    }
+    try {
+      gates.push(await baseBranchCondition(cwd, flow, mergedCommit ?? undefined, flow.pr.url && deps.tracker && await deps.tracker.detect() ? (await deps.tracker.prStatus(flow.pr.url)).baseRefName : undefined, commitContainedIn));
+    } catch {
+      gates.push(unevaluableGate("base-branch"));
+    }
+    gates.push(taskGate(flow));
+    gates.push(ownerGate(flow));
+    try {
+      gates.push(await reviewGate({
+        cwd,
+        flowDir: dir,
+        flow,
+        tracker: deps.tracker,
+        ...deps.externalCommentsGate ? { externalCommentsGate: deps.externalCommentsGate } : {},
+        ...mergedCommit ? { mergedCommit } : {}
+      }));
+    } catch {
+      gates.push(unevaluableGate("review"));
+    }
+    try {
+      const health = await deps.healthGate(cwd);
+      gates.push(healthGateOutcome(health));
+    } catch {
+      gates.push(unevaluableGate("health"));
+    }
+    if (deps.securityGate) {
+      try {
+        const security = await deps.securityGate(cwd);
+        if (security) {
+          gates.push({ name: "security", status: security.status, detail: security.detail });
+        }
+      } catch {
+        gates.push(unevaluableGate("security"));
+      }
+    }
+    gates.push(confirmationOutcome);
+    return { gates, confirmationToken, evaluatedHeadCommit, pr };
+  }
   async function mutate(cwd, id, run) {
     const dir = await resolveFlowDir(cwd, id);
     return withFileLock(flowLockPath(cwd, dir), async () => {
@@ -26756,6 +26935,27 @@ function createFlowService(deps) {
         return save(cwd, dir, flow, "implemented", detail);
       });
     },
+    async checkComplete({ cwd, id, mergedCommit, confirmToken }) {
+      const { dir, flow } = await load(cwd, id);
+      const merged = Boolean(mergedCommit);
+      const allowed = completionAdmitted(flow.status, merged);
+      const transition = allowed ? { allowed, detail: `${flow.status} \u2192 completing` } : {
+        allowed,
+        detail: flow.status === "done" ? "already done" : flow.status === "in-progress" ? `in-progress: record the PR first (\`keryx flow implemented ${flow.id} --pr <url>\`), or pass a merged commit` : `"${flow.status}" cannot move to completing; complete runs from "implemented" (or "in-progress" with a merged commit)`
+      };
+      const evaluation = await evaluateCompletionGates(cwd, dir, flow, mergedCommit ?? undefined, confirmToken);
+      return {
+        id: flow.id,
+        status: flow.status,
+        updatedAt: flow.updatedAt,
+        checkedAt: now(),
+        transition,
+        merge: prMergeState(evaluation.pr, evaluation.gates),
+        gates: evaluation.gates,
+        passed: allowed && evaluation.gates.every((gate) => gate.status !== "fail"),
+        confirmationRequired: flow.gates?.confirmation === true
+      };
+    },
     async complete({
       cwd,
       id,
@@ -26776,97 +26976,7 @@ function createFlowService(deps) {
         } else {
           flow = await transition(cwd, dir, flow, "completing", "completing");
         }
-        const gates = [];
-        try {
-          await assertAcIntact(cwd, dir, flow);
-          const criteria = await readAcCriteria(cwd, dir);
-          const missing = criteria.filter((criterion) => !flow.acConfirmed[criterion]);
-          gates.push(missing.length === 0 && criteria.length > 0 ? { name: "acceptance-criteria", status: "pass", detail: `${criteria.length} confirmed` } : {
-            name: "acceptance-criteria",
-            status: "fail",
-            detail: criteria.length === 0 ? "no criteria found" : `unconfirmed: ${missing.join(", ")}`
-          });
-        } catch {
-          gates.push(unevaluableGate("acceptance-criteria"));
-        }
-        let confirmationToken;
-        let confirmationOutcome;
-        try {
-          const confirmation = await confirmationGate(cwd, dir, flow, confirmToken, completionTarget({ merged: Boolean(mergedCommit), prUrl: flow.pr.url }), deps.now());
-          confirmationOutcome = confirmation.outcome;
-          confirmationToken = confirmation.stored;
-        } catch {
-          confirmationOutcome = unevaluableGate("confirmation");
-        }
-        let evaluatedHeadCommit = mergedCommit ?? undefined;
-        if (mergedCommit) {
-          try {
-            const merge = deps.mainMergeGate ? await deps.mainMergeGate(cwd, mergedCommit) : await verifyCommitOnMain(cwd, mergedCommit);
-            gates.push({ name: "main-merge", status: merge.status, detail: merge.detail });
-          } catch {
-            gates.push(unevaluableGate("main-merge"));
-          }
-        } else if (!flow.pr.url) {
-          gates.push({ name: "pull-request", status: "fail", detail: "no PR recorded" });
-        } else {
-          try {
-            if (deps.tracker && await deps.tracker.detect()) {
-              const pr = await deps.tracker.prStatus(flow.pr.url);
-              if (typeof pr.headSha === "string" && pr.headSha !== "") {
-                evaluatedHeadCommit ??= pr.headSha;
-              }
-              gates.push(pr.exists && pr.checksGreen === true ? { name: "pull-request", status: "pass", detail: "PR exists, checks green" } : {
-                name: "pull-request",
-                status: "fail",
-                detail: !pr.exists ? "PR not found" : "PR checks not green"
-              });
-            } else {
-              gates.push({
-                name: "pull-request",
-                status: "skipped",
-                detail: "tracker unavailable; verify PR checks manually"
-              });
-            }
-          } catch {
-            gates.push(unevaluableGate("pull-request"));
-          }
-        }
-        try {
-          gates.push(await baseBranchCondition(cwd, flow, mergedCommit ?? undefined, flow.pr.url && deps.tracker && await deps.tracker.detect() ? (await deps.tracker.prStatus(flow.pr.url)).baseRefName : undefined, commitContainedIn));
-        } catch {
-          gates.push(unevaluableGate("base-branch"));
-        }
-        gates.push(taskGate(flow));
-        gates.push(ownerGate(flow));
-        try {
-          gates.push(await reviewGate({
-            cwd,
-            flowDir: dir,
-            flow,
-            tracker: deps.tracker,
-            ...deps.externalCommentsGate ? { externalCommentsGate: deps.externalCommentsGate } : {},
-            ...mergedCommit ? { mergedCommit } : {}
-          }));
-        } catch {
-          gates.push(unevaluableGate("review"));
-        }
-        try {
-          const health = await deps.healthGate(cwd);
-          gates.push(healthGateOutcome(health));
-        } catch {
-          gates.push(unevaluableGate("health"));
-        }
-        if (deps.securityGate) {
-          try {
-            const security = await deps.securityGate(cwd);
-            if (security) {
-              gates.push({ name: "security", status: security.status, detail: security.detail });
-            }
-          } catch {
-            gates.push(unevaluableGate("security"));
-          }
-        }
-        gates.push(confirmationOutcome);
+        const { gates, confirmationToken, evaluatedHeadCommit } = await evaluateCompletionGates(cwd, dir, flow, mergedCommit ?? undefined, confirmToken);
         const passed = gates.every((gate) => gate.status !== "fail");
         const tamperDetail = await acTamperDetail(cwd, dir, flow);
         const recordedGates = tamperDetail === undefined ? gates : [
@@ -39815,7 +39925,7 @@ var HELP_GROUPS = [
     kind: "slash",
     name: "/governance",
     group: "Automation",
-    summary: "Show the last governance report, or run one in the background."
+    summary: "Flows with their summary and stated effect \u2014 check an open one, complete it once the check passes and the PR is merged; the last report in its own tab, or run one in the background."
   },
   {
     kind: "slash",
@@ -39835,6 +39945,12 @@ var HELP_GROUPS = [
     group: "Automation",
     summary: "Drive this session from a Telegram topic: send lines, get replies, answer approvals. Off by default; [name|off|status]."
   },
+  {
+    kind: "slash",
+    name: "/channels",
+    group: "Automation",
+    summary: "Connect, test or disconnect Telegram for this machine: bot token, one-time code, group. [status]."
+  },
   {
     kind: "cli",
     name: "acp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.48",
+  "version": "0.3.51",
   "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": {