@mrciphersmith/keryx 0.3.49 → 0.3.52

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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.49",
+  "version": "0.3.52",
   "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/gdskills/bundled/skills/core/reviewer-skill-creator/SKILL.detail.md

@@ -171,9 +171,10 @@ Read three things off it before running for real:
   the reviewer will cite a rule the project will not have. `differs` means a
   file already answers that reference with other content.
 
-A dry-run does not run the security gate that a real run applies to every file
-it writes, so a `would-…` status can be optimistic: the real run may still block
-a package, or report a rule as `unresolved` with `blocked by the security gate`.
+A dry-run runs the same security gate a real run does, on the text that would
+be written, so a `would-…` status already says what the gate would do. A file
+the gate would refuse is `would-refuse`, and a file it would change or flag
+carries the reason on its row (section 3, "The security gate on import").
 
 ### 3. The real run, and what it writes
 
@@ -305,6 +306,107 @@ to overwrite`, and the rule rows are re-resolved — `present` for both files
 written above, the second with `the reviewer reads
 .metaproject/rules/project/core/error-handling.mdc`.
 
+**The security gate on import.** `keryx skills import`, `keryx review import`
+and `keryx skills update` pass every `SKILL.md` and rule through the security
+gate on the final text, while planning, so a dry run reports it too. The gate
+does not write silently:
+
+- A secret is masked in what is written, and the row says so: `redacted by the
+  security gate (…)`. On a dry run, `would be redacted by the security gate (…)`.
+- Any other finding follows the project's security mode and is reported on the
+  row as `flagged by the security gate (…)`.
+- A **prompt-injection** finding refuses the file in every security mode. The row
+  status is `refused` (`would-refuse` on a dry run), the reason is the gate's own
+  leak-safe summary (policy ids and counts, never the matched text), nothing is
+  written and no scaffold is left. The other packages and rules go on.
+- **With the security module disabled** the guard reports nothing, so the import
+  runs the deterministic prompt-injection detector itself and refuses on a match
+  exactly as above; the row reason says `the security module is disabled, so the
+  import ran its own injection check`. A secret is still masked by the floor
+  redaction; clean text imports as usual.
+- A rule cited **only** by refused (`would-refuse`) packages is not written. Its
+  row reads `skipped — cited only by a refused package`, on a dry run and a real
+  run alike; a rule an imported package also cites is handled as before.
+- **Exit code.** A real run that produced any `refused` row prints every row (text
+  or `--json`) and then exits 1. A dry run, whose rows say `would-refuse`, exits 0.
+- The file is gated once, before anything is written, and the text written is the
+  text gated: a refusal leaves no scaffold, registry entry or catalog row, and
+  never overwrites an installed `SKILL.md` on `--force` or update.
+- `--allow-flagged` writes a prompt-injection-flagged file anyway, after you have
+  read it. The row then reads `flagged by the security gate (…), written because
+  --allow-flagged` (`would be written because --allow-flagged` on a dry run). It
+  never overrides a block by the project's security mode: under mode `enforced`
+  a secret is refused with or without the flag.
+
+The flag belongs to all three commands: `keryx skills import … [--allow-flagged]`,
+`keryx review import … [--allow-flagged]`, `keryx skills update … [--allow-flagged]`.
+The summary line gains `refused: N` (`would-refuse: N` on a dry run) only when
+N is above zero, and the note under it names `--allow-flagged` only when a refused
+row carries a prompt-injection finding (the flag cannot change any other
+refusal). This is the output for an overlay with two reviewers, one whose
+body tries to override the agent's instructions and asks it to disclose its
+own context, and one that holds the AWS documentation placeholder access key:
+
+```
+$ keryx review import --from ./ov --only 'review-acme-*' --dry-run
+# skills import
+
+from: ./ov
+dry-run: yes
+force: no
+imported: 0 overwritten: 0 updated: 0 skipped: 0 would-import: 1 would-overwrite: 0 would-refuse: 1
+…
+## packages
+
+- review/review-acme-inj: would-refuse — [security] pass: 2 finding(s) (prompt-injection:2)
+- review/review-acme-key: would-import — would be redacted by the security gate ([security] fail: 1 finding(s) (secret:1)) — review-orchestrator will dispatch this after `keryx review reviewers` lists it
+
+A refused file was not written. A prompt-injection refusal can be overridden after you read the file: run the command again with --allow-flagged.
+…
+
+$ keryx review import --from ./ov --only 'review-acme-*'
+…
+imported: 1 overwritten: 0 updated: 0 skipped: 0 would-import: 0 would-overwrite: 0 refused: 1
+
+- review/review-acme-inj: refused — [security] pass: 2 finding(s) (prompt-injection:2)
+- review/review-acme-key: imported — redacted by the security gate ([security] fail: 1 finding(s) (secret:1)) — review-orchestrator will dispatch this after `keryx review reviewers` lists it
+…
+
+$ keryx review import --from ./ov --only 'review-acme-inj' --dry-run --allow-flagged
+…
+- review/review-acme-inj: would-import — flagged by the security gate ([security] pass: 2 finding(s) (prompt-injection:2)), would be written because --allow-flagged — review-orchestrator will dispatch this after `keryx review reviewers` lists it
+…
+```
+
+Row statuses, with the gate in them: `imported`, `overwritten`, `updated`,
+`skipped`, `would-import`, `would-overwrite`, `refused`, `would-refuse`.
+
+In `--json` a row carries a `security` object when the gate had something to say
+about it, and none otherwise. The refused row above, trimmed:
+
+```json
+{
+  "name": "review-acme-inj",
+  "module": "review",
+  "status": "would-refuse",
+  "reason": "[security] pass: 2 finding(s) (prompt-injection:2)",
+  "security": {
+    "action": "warn",
+    "findings": [
+      { "policyId": "prompt-injection.ignore-instructions", "category": "prompt-injection", "action": "warn" },
+      …
+    ],
+    "redacted": false,
+    "refused": true
+  }
+}
+```
+
+`security.redacted` is true when the gate changed the bytes that are, or would
+be, written; `security.refused` is true when the file was not (or would not be)
+written. A caller that used to read `status` alone must now treat `refused` and
+`would-refuse` as failures to import that exit 0.
+
 ### 4. Reading `keryx review reviewers`
 
 ```