@mrciphersmith/keryx 0.2.84 → 0.2.88

package/dist/core.js

@@ -10291,6 +10291,7 @@ var init_wiki_layer = __esm(() => {
 init_fs();
 var exports_service = {};
 __export(exports_service, {
+  baseBranchCondition: () => baseBranchCondition,
   createFlowService: () => createFlowService
 });
 import { mkdir as mkdir5, readFile as readFile9, rename as rename3 } from "fs/promises";
@@ -13098,6 +13099,7 @@ function createFlowService(deps) {
           acChecksum: null,
           acConfirmed: {},
           pr: { url: null },
+          ...input.baseBranch === undefined ? {} : { baseBranch: input.baseBranch },
           tasks: DEFAULT_TASKS.map((task) => ({ ...task, status: "todo" })),
           history: [{ at: createdAt, event: "created" }]
         };
@@ -13306,6 +13308,10 @@ function createFlowService(deps) {
           if (!pr.isDraft) {
             detail += " (warning: PR is not a draft)";
           }
+          if (flow.baseBranch === undefined && typeof pr.baseRefName === "string" && pr.baseRefName !== "") {
+            flow.baseBranch = pr.baseRefName;
+            detail += ` (base: ${pr.baseRefName})`;
+          }
         } else {
           detail += " (tracker unavailable: existence not verified)";
         }
@@ -13357,6 +13363,7 @@ function createFlowService(deps) {
             detail: "tracker unavailable; verify PR checks manually"
           });
         }
+        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));
         gates.push(taskGate(flow));
         try {
           gates.push(await reviewGate({
@@ -13661,6 +13668,70 @@ function buildIssueComment(flow, gates) {
   ].join(`
 `);
 }
+async function baseBranchCondition(cwd, flow, mergedCommit, prBase, containedIn) {
+  const recorded = flow.baseBranch;
+  if (recorded === undefined || recorded.trim() === "") {
+    return {
+      name: "base-branch",
+      status: "skipped",
+      detail: "not recorded: this flow never named a base branch, so there is nothing to compare the merge against. Not a pass \u2014 `keryx flow init --base <branch>` or `flow implemented --pr <url>` records one."
+    };
+  }
+  if (mergedCommit !== undefined) {
+    const contained = await containedIn(cwd, mergedCommit, `origin/${recorded}`);
+    if (contained === null) {
+      return {
+        name: "base-branch",
+        status: "fail",
+        detail: `unobserved: origin/${recorded} could not be resolved, so whether ${mergedCommit} landed there is unknown. Fetch the remote (\`git fetch origin ${recorded}\`) and re-run; an unresolvable base is not a passing one.`
+      };
+    }
+    return contained ? {
+      name: "base-branch",
+      status: "pass",
+      detail: `${mergedCommit} is contained in origin/${recorded}, the base this flow recorded`
+    } : {
+      name: "base-branch",
+      status: "fail",
+      detail: `violated: this flow recorded base ${recorded}, but ${mergedCommit} is not contained in origin/${recorded}. The merge landed somewhere else.`
+    };
+  }
+  if (prBase === undefined || prBase === null || prBase === "") {
+    return {
+      name: "base-branch",
+      status: "fail",
+      detail: `unobserved: this flow recorded base ${recorded}, but the tracker did not report the pull request's base. An unread base is not a matching one.`
+    };
+  }
+  return prBase === recorded ? {
+    name: "base-branch",
+    status: "pass",
+    detail: `the pull request targets ${prBase}, the base this flow recorded`
+  } : {
+    name: "base-branch",
+    status: "fail",
+    detail: `violated: this flow recorded base ${recorded}, but the pull request now targets ${prBase}. It was retargeted after the base was recorded.`
+  };
+}
+async function commitContainedIn(cwd, commit, ref) {
+  if (!/^[0-9a-f]{7,64}$/i.test(commit)) {
+    return null;
+  }
+  const resolved = Bun.spawn(["git", "rev-parse", "--verify", `${ref}^{commit}`], {
+    cwd,
+    stdout: "ignore",
+    stderr: "ignore"
+  });
+  if (await resolved.exited !== 0) {
+    return null;
+  }
+  const process2 = Bun.spawn(["git", "merge-base", "--is-ancestor", commit, ref], {
+    cwd,
+    stdout: "ignore",
+    stderr: "ignore"
+  });
+  return await process2.exited === 0;
+}
 async function verifyCommitOnMain(cwd, commit) {
   if (!/^[0-9a-f]{7,64}$/i.test(commit)) {
     return { status: "fail", detail: "merged commit must be a hexadecimal Git commit id" };
@@ -18423,63 +18494,112 @@ var CONTRACTS = [
   {
     name: "agent-event",
     fileName: "agent-event.schema.json",
-    description: "Append-only lifecycle event emitted by orchestrators and subagents."
+    description: "Append-only lifecycle event emitted by orchestrators and subagents.",
+    enforcement: {
+      kind: "none",
+      reason: "Events are appended by whichever agent is running, in that agent's own runtime. No keryx process sits between the emitter and the log, so there is no point at which a malformed event could be refused rather than written."
+    }
   },
   {
     name: "flow-orchestrator-input",
     fileName: "flow-orchestrator-input-contract.schema.json",
     description: "Dispatch payload handed to flow-orchestrator (request + base branch + completion outcome + constraints).",
-    sourcePath: "src/gdskills/bundled/skills/orchestration/flow-orchestrator/input-contract.schema.json"
+    sourcePath: "src/gdskills/bundled/skills/orchestration/flow-orchestrator/input-contract.schema.json",
+    enforcement: {
+      kind: "none",
+      reason: "This payload is handed from one AGENT to another. In a session driven by a host agent's own dispatch tool, no keryx process is on that path, so nothing can refuse a malformed dispatch. Same structural position as reviewer-input, recorded for the same reason. Registering it made `keryx skills contracts validate --schema flow-orchestrator-input` possible, which is a validator an agent must remember to run, not an enforcement."
+    }
   },
   {
     name: "review-pr-feedback-input",
     fileName: "review-pr-feedback-input-contract.schema.json",
     description: "Request handed to review-pr-feedback (PR reference, --fix, and the operator confirmation --fix requires).",
-    sourcePath: "src/gdskills/bundled/skills/review/review-pr-feedback/input-contract.schema.json"
+    sourcePath: "src/gdskills/bundled/skills/review/review-pr-feedback/input-contract.schema.json",
+    enforcement: {
+      kind: "none",
+      reason: "The request is what an operator or a host agent hands the skill before any keryx command runs, so keryx is not yet in the path when the payload would have to be refused. This is the one where that hurts most: `--fix` merges third-party review comments into somebody else's pull request, and `operator_confirmed` is the fence. The conditional is expressed in the schema and `keryx skills contracts validate --schema review-pr-feedback-input` will apply it \u2014 but only when something invokes it."
+    }
   },
   {
     name: "review-pr-feedback-output",
     fileName: "review-pr-feedback-output-contract.schema.json",
     description: "Result review-pr-feedback returns: verdict counts, the injection-screen record, and what the fix run merged.",
-    sourcePath: "src/gdskills/bundled/skills/review/review-pr-feedback/output-contract.schema.json"
+    sourcePath: "src/gdskills/bundled/skills/review/review-pr-feedback/output-contract.schema.json",
+    enforcement: {
+      kind: "opt-in",
+      module: "src/commands/review.ts",
+      switchedOnBy: "keryx review comments reply --result <file>",
+      refuses: "A result that contradicts itself, before the pass is built and before any network call: an analyze-mode run reporting a branch and a merge, or a record saying the injection screen never ran while claiming it excluded comments."
+    }
   },
   {
     name: "job-orchestrator-state",
     fileName: "job-orchestrator-state.schema.json",
     description: "Persisted job package state (.metaproject/jobs/<name>/state.json), written by `keryx job`.",
-    sourcePath: "src/gdskills/bundled/skills/orchestration/job-orchestrator/state.schema.json"
+    sourcePath: "src/gdskills/bundled/skills/orchestration/job-orchestrator/state.schema.json",
+    enforcement: {
+      kind: "production",
+      module: "src/job/store.ts",
+      refuses: "`writeJob` refuses to write a state file that does not satisfy the schema, so an invalid job package cannot reach disk."
+    }
   },
   {
     name: "orchestrator-state",
     fileName: "orchestrator-state.schema.json",
-    description: "Persisted resumable orchestrator state."
+    description: "Persisted resumable orchestrator state.",
+    enforcement: {
+      kind: "none",
+      reason: "No keryx command reads or writes this file. It describes state an orchestrator agent persists for itself, in its own runtime, so there is no keryx-owned write path to refuse at. Contrast job-orchestrator-state, which looks similar and IS enforced for exactly one reason: `keryx job` writes that one."
+    }
   },
   {
     name: "review-finding",
     fileName: "review-finding.schema.json",
-    description: "Normalized reviewer finding consumed by review-orchestrator and learning flows."
+    description: "Normalized reviewer finding consumed by review-orchestrator and learning flows.",
+    enforcement: {
+      kind: "production",
+      module: "src/review/managed.ts",
+      refuses: "`createManagedReviewPackage` refuses to record findings that do not satisfy the schema, and the disposition sub-schema is applied the same way, so a review round cannot be written with a malformed finding or an unreadable outcome."
+    }
   },
   {
     name: "subagent-dispatch",
     fileName: "subagent-dispatch.schema.json",
-    description: "Orchestrator-to-subagent dispatch payload."
+    description: "Orchestrator-to-subagent dispatch payload.",
+    enforcement: {
+      kind: "none",
+      reason: "The dispatch is built and consumed inside the harness without the canonical schema being loaded: `subagent-dispatch` appears only as a label on the extension metadata. Its sibling `subagent-result` IS validated, because the harness parses a child's reply back and has to decide whether it is well-formed; nothing performs the equivalent act on the way out."
+    }
   },
   {
     name: "subagent-result",
     fileName: "subagent-result.schema.json",
-    description: "Subagent-to-orchestrator result payload."
+    description: "Subagent-to-orchestrator result payload.",
+    enforcement: {
+      kind: "production",
+      module: "src/harness/external/runtime.ts",
+      refuses: "A child's reply that does not parse as a well-formed result is rejected when the harness reads it back, so a malformed result cannot be persisted as if the child had succeeded."
+    }
   },
   {
     name: "task-implementer-input",
     fileName: "task-implementer-input-contract.schema.json",
     description: "Task request handed to task-implementer (task + workspace + automation), validated before dispatch.",
-    sourcePath: "src/gdskills/bundled/skills/orchestration/task-implementer/input-contract.schema.json"
+    sourcePath: "src/gdskills/bundled/skills/orchestration/task-implementer/input-contract.schema.json",
+    enforcement: {
+      kind: "none",
+      reason: "Dispatched agent-to-agent, like flow-orchestrator-input. The skill's Phase 1.4 lists five `ASSERT \u2026 \u2192 ABORT(\u2026)` refusals; registering the contract is what lets `keryx skills contracts validate` perform them, and nothing forces that call. The comment beside this registration has said so since it was written."
+    }
   },
   {
     name: "task-implementer-output",
     fileName: "task-implementer-output-contract.schema.json",
     description: "JSON result task-implementer writes in Phase 6.1 before it emits its STATUS line.",
-    sourcePath: "src/gdskills/bundled/skills/orchestration/task-implementer/output-contract.schema.json"
+    sourcePath: "src/gdskills/bundled/skills/orchestration/task-implementer/output-contract.schema.json",
+    enforcement: {
+      kind: "none",
+      reason: "The skill writes this file itself, in its own runtime, and no keryx command reads it back. Contrast subagent-result, which is the same shape of thing and IS enforced for one reason: the harness reads that one back and must decide whether it is well-formed."
+    }
   }
 ];
 async function loadSchema(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.84",
+  "version": "0.2.88",
   "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": {
@@ -54,6 +54,7 @@
     "check": "bun run lint && bun run typecheck && bun run typecheck:scripts && bun test",
     "check:core": "bun run lint && bun run typecheck && bun run typecheck:scripts && bun run test:core",
     "check:doc-links": "bun scripts/check-doc-links.ts",
+    "check:retired-spellings": "bun scripts/check-retired-cli-spellings.ts",
     "baseline:review-precision": "bun scripts/review-precision-baseline.ts",
     "test:guards": "bun test src/lib/config-dir.ast.test.ts src/lib/config-dir.readers.test.ts src/lib/production-graph.test.ts src/harness/policy/profiles.test.ts src/lib/serve-server.test.ts src/gdskills/agent-catalogue-xref.test.ts src/gdskills/enforcement-claims.test.ts",
     "lint": "eslint ."

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

@@ -198,13 +198,15 @@ keryx flow init --issue <url>
 or:
 
 ```bash
-keryx flow init --title "<short formalized problem>"
+keryx flow init --title "<short formalized problem>" --base "<branch the work must land on>"
 ```
 
 5. Run `keryx flow status <id>` and read the flow package.
-6. Record the git base branch from which the flow branch was created in
-   `context.md` and `journal.md`; the PR must later be merged into this exact
-   branch.
+6. `--base` records the branch in the flow record itself, where the completion
+   gate reads it. Note it in `context.md` and `journal.md` as well if it helps a
+   reader, but prose is not what the gate checks: before this flag the base
+   survived only as something an agent had written down, which is detectable at
+   dispatch and undetectable at completion.
 
 ## Phase 1: Initialize The Flow Package
 
@@ -442,9 +444,16 @@ How should this flow end?
 
 3. Follow the selected outcome:
 
-- **A - Create PR and merge:** create or confirm a PR in the author's name.
-  Preserve the base branch recorded during initialization. Do not mark the
-  flow implemented or complete before the PR is merged into that branch.
+- **A - Create PR and merge:** create or confirm a PR in the author's name,
+  opened against the base recorded at initialization. Do not mark the flow
+  implemented or complete before the PR is merged into that branch.
+
+  `keryx flow complete` now checks this rather than asking you to confirm it by
+  eye: its `base-branch` condition compares where the merge landed against the
+  base in the record, and refuses when they differ. It reports three states,
+  and only one of them is a pass — a flow that recorded no base gets
+  `not recorded`, which is not a pass either. So the useful thing to do here is
+  make sure the base WAS recorded, not to re-verify the merge yourself.
 
 ### A dispatched run answers the question from its input
 

package/src/gdskills/bundled/skills/review/review-pr-feedback/SKILL.md

@@ -591,6 +591,7 @@ merge, with every reviewer unanswered.
 
 ```bash
 keryx review comments reply --repo <owner/repo> --pr <n> --outcomes <file|-> \
+                            --result <this-run's-output.json> \
                             --sha <mergedHeadSha> --final [--dry-run] [--flow-link <url>]
 ```
 
@@ -598,6 +599,17 @@ Run it **after** the merge, never during the loop: a reply written mid-round sta
 an intention, and by the time the reviewer reads it the intention has changed.
 `--final` is required by the command; it is not a reminder that can be skipped.
 
+`--result` hands this run's own output to the one keryx-owned point that can
+refuse it. Write the result described in Step 11 to a file first and pass it
+here: the command validates it against `review-pr-feedback-output` BEFORE
+posting anything, so a result that contradicts itself — analyze mode reporting a
+merge, or a screen recorded as never having run while excluding comments — stops
+here instead of being published under your name.
+
+Optional in the CLI, and the registry records this contract as `opt-in` rather
+than enforced for exactly that reason: omit the flag and nothing is checked.
+Passing it is the whole of the enforcement.
+
 The judgement is yours; the command owns the mechanics. It routes an inline comment
 to its thread (`pulls/{n}/comments/{id}/replies`) and a review-submission body or
 PR-level comment to one top-level comment that names what it answers — GitHub