@mrciphersmith/keryx 0.3.57 → 0.3.59

package/dist/core.js

@@ -24100,6 +24100,8 @@ __export(exports_service2, {
   AC_KINDS: () => AC_KINDS,
   CONFIRMATION_CAVEAT: () => CONFIRMATION_CAVEAT,
   DEFAULT_OUTCOME_AUTHOR: () => DEFAULT_OUTCOME_AUTHOR,
+  ORIGIN_KINDS: () => ORIGIN_KINDS,
+  ORIGIN_READINGS: () => ORIGIN_READINGS,
   OUTCOME_AUTHORS: () => OUTCOME_AUTHORS,
   OUTCOME_AUTHOR_READINGS: () => OUTCOME_AUTHOR_READINGS,
   OUTCOME_HINT: () => OUTCOME_HINT,
@@ -24119,6 +24121,7 @@ __export(exports_service2, {
   confirmPreconditionError: () => confirmPreconditionError,
   createFlowService: () => createFlowService,
   describeAcKind: () => describeAcKind,
+  effectiveOutcomeAuthor: () => effectiveOutcomeAuthor,
   evaluatedVerdict: () => evaluatedVerdict,
   extractCriterionTokens: () => extractCriterionTokens,
   factsOnlyVerdict: () => factsOnlyVerdict,
@@ -24128,7 +24131,10 @@ __export(exports_service2, {
   hashDiff: () => hashDiff,
   intentNoteForNewFlow: () => intentNoteForNewFlow,
   isFrozen: () => isFrozen,
+  isOriginKind: () => isOriginKind,
   notCheckableVerdict: () => notCheckableVerdict,
+  originDetailLines: () => originDetailLines,
+  originSummary: () => originSummary,
   outcomeBulletsFrom: () => outcomeBulletsFrom,
   parseAcceptanceCriteria: () => parseAcceptanceCriteria,
   parseOutcomeAuthor: () => parseOutcomeAuthor,
@@ -24137,12 +24143,15 @@ __export(exports_service2, {
   readAcCheckEnabled: () => readAcCheckEnabled,
   readAcKindRecords: () => readAcKindRecords,
   readFlow: () => readFlow,
+  readOrigin: () => readOrigin,
+  readOriginKind: () => readOriginKind,
   readOutcomeAuthor: () => readOutcomeAuthor,
   renderAcCheckAdvisoryNotice: () => renderAcCheckAdvisoryNotice,
   renderAcCheckReport: () => renderAcCheckReport,
   renderAcKindDistribution: () => renderAcKindDistribution,
   reportFromRecords: () => reportFromRecords,
   resolveFlowDir: () => resolveFlowDir,
+  resolveOrigin: () => resolveOrigin,
   sectionOf: () => sectionOf,
   selectMatchedHunks: () => selectMatchedHunks,
   statementFrom: () => statementFrom,
@@ -25613,6 +25622,129 @@ function parseOutcomeAuthor(raw, flag = "--outcome-author") {
   const shown = typeof raw === "string" ? `"${raw}"` : "nothing";
   throw new Error(`${flag} must be one of: ${OUTCOME_AUTHORS.join(", ")} (got ${shown}).`);
 }
+
+// src/flow/origin.ts
+var ORIGIN_KINDS = ["human-request", "agent-finding", "agent-proposal"];
+var ORIGIN_READINGS = [...ORIGIN_KINDS, "unknown"];
+function isOriginKind(value) {
+  return typeof value === "string" && ORIGIN_KINDS.includes(value);
+}
+function nonBlank(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function readOrigin(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return;
+  const raw = value;
+  if (!isOriginKind(raw.kind))
+    return;
+  const origin = { kind: raw.kind };
+  if (typeof raw.quote === "string" && raw.quote.length > 0)
+    origin.quote = raw.quote;
+  if (typeof raw.source === "string" && raw.source.length > 0)
+    origin.source = raw.source;
+  return origin;
+}
+function readOriginKind(value) {
+  return readOrigin(value)?.kind ?? "unknown";
+}
+function resolveOrigin(input) {
+  if (!isOriginKind(input.kind)) {
+    return {
+      note: `origin kind "${input.kind}" is not one of: ${ORIGIN_KINDS.join(", ")}; origin stays unknown.`
+    };
+  }
+  const hasQuote = nonBlank(input.quote);
+  const hasSource = nonBlank(input.source);
+  if (input.kind === "human-request") {
+    if (!hasQuote && !hasSource) {
+      return { note: "origin human-request needs a verbatim --quote and a --source; neither was given, origin stays unknown." };
+    }
+    if (!hasQuote) {
+      return { note: "origin human-request needs a verbatim --quote of the human's first message; none was given, origin stays unknown." };
+    }
+    if (!hasSource) {
+      return { note: "origin human-request needs a --source (channel, message id or time); none was given, origin stays unknown." };
+    }
+  } else if (!hasSource) {
+    return { note: `origin ${input.kind} needs a --source (the check, review or test that produced it); none was given, origin stays unknown.` };
+  }
+  const origin = { kind: input.kind };
+  if (hasQuote)
+    origin.quote = input.quote;
+  if (hasSource)
+    origin.source = input.source;
+  return { origin };
+}
+function effectiveOutcomeAuthor(flow) {
+  const explicit = readOutcomeAuthor(flow.outcomeAuthor);
+  if (explicit !== "unknown")
+    return explicit;
+  return readOrigin(flow.origin) === undefined ? "unknown" : "agent";
+}
+function originSummary(origin) {
+  if (origin === undefined)
+    return "unknown";
+  const parts = [origin.kind];
+  if (origin.quote !== undefined)
+    parts.push(`quote: ${JSON.stringify(origin.quote)}`);
+  if (origin.source !== undefined)
+    parts.push(`source: ${origin.source}`);
+  return parts.join("; ");
+}
+function originDetailLines(origin, indent = "") {
+  if (origin === undefined)
+    return [`${indent}origin: unknown`];
+  const lines = [`${indent}origin: ${origin.kind}`];
+  if (origin.quote !== undefined) {
+    const [first = "", ...rest] = origin.quote.split(`
+`);
+    lines.push(`${indent}  quote:  \xAB${first}`, ...rest.map((line) => `${indent}          ${line}`));
+    lines[lines.length - 1] += "\xBB";
+  }
+  if (origin.source !== undefined)
+    lines.push(`${indent}  source: ${origin.source}`);
+  return lines;
+}
+var REQUEST_LABEL = "\u0417\u0430\u043F\u0440\u043E\u0441 (\u0434\u043E\u0441\u043B\u043E\u0432\u043D\u043E)";
+var SOURCE_LABEL = "\u0418\u0441\u0442\u043E\u0447\u043D\u0438\u043A";
+var FORMALIZATION_LABEL = "\u042D\u0444\u0444\u0435\u043A\u0442 (\u0444\u043E\u0440\u043C\u0430\u043B\u0438\u0437\u0430\u0446\u0438\u044F \u0430\u0433\u0435\u043D\u0442\u0430)";
+var OBSERVE_LABEL = "\u041A\u0430\u043A \u043D\u0430\u0431\u043B\u044E\u0434\u0430\u0442\u044C (\u043F\u0440\u0435\u0434\u043B\u043E\u0436\u0435\u043D\u0438\u0435 \u0430\u0433\u0435\u043D\u0442\u0430)";
+var REQUEST_PLACEHOLDER = "<the human's request, verbatim, no translation or paraphrase>";
+var SOURCE_PLACEHOLDER = "<where the finding or proposal came from: check, review, test or discussion>";
+var FORMALIZATION_PLACEHOLDER = "<the effect that has to be true when this flow is done, in your own words>";
+var OBSERVE_PLACEHOLDER = "<how the effect can be observed once the flow is done>";
+var ORIGIN_PLACEHOLDER_BULLETS = [
+  `- ${REQUEST_LABEL}: ${REQUEST_PLACEHOLDER}`,
+  `- ${SOURCE_LABEL}: ${SOURCE_PLACEHOLDER}`,
+  `- ${FORMALIZATION_LABEL}: ${FORMALIZATION_PLACEHOLDER}`,
+  `- ${OBSERVE_LABEL}: ${OBSERVE_PLACEHOLDER}`
+];
+function renderOriginBullets(origin) {
+  const first = [];
+  if (origin.kind === "human-request") {
+    first.push(...bulletWithText(REQUEST_LABEL, origin.quote === undefined ? undefined : `\xAB${origin.quote}\xBB`, REQUEST_PLACEHOLDER));
+    if (origin.source !== undefined)
+      first[first.length - 1] += ` (source: ${origin.source})`;
+  } else {
+    first.push(...bulletWithText(SOURCE_LABEL, origin.source, SOURCE_PLACEHOLDER));
+    if (origin.quote !== undefined)
+      first.push(...bulletWithText(REQUEST_LABEL, `\xAB${origin.quote}\xBB`, REQUEST_PLACEHOLDER));
+  }
+  return [
+    ...first,
+    `- ${FORMALIZATION_LABEL}: ${FORMALIZATION_PLACEHOLDER}`,
+    `- ${OBSERVE_LABEL}: ${OBSERVE_PLACEHOLDER}`
+  ];
+}
+function bulletWithText(label, text, placeholder) {
+  if (text === undefined)
+    return [`- ${label}: ${placeholder}`];
+  const lines = text.split(`
+`);
+  const head = `- ${label}: ${lines[0] ?? ""}`;
+  return [head, ...lines.slice(1).map((line) => `    ${line}`)];
+}
 // src/flow/identity.ts
 function resolveSignerIdentity(input) {
   const stated = input.stated?.trim();
@@ -25908,6 +26040,23 @@ function flowStateSchema() {
         enum: ["agent", "human"],
         description: "Who wrote the outcome criterion. Written by `flow init --outcome-author` (default `agent`; `human` only when the flag says so, never inferred) and changed only by `flow outcome author`, which journals the change. Absent on flows created before the field existed, and read as `unknown` (neither agent nor human). Gates nothing."
       },
+      origin: {
+        type: "object",
+        additionalProperties: false,
+        required: ["kind"],
+        description: "Where the flow came from. Written by `flow init --origin <kind> [--quote] [--source]` and changed only by `flow origin set`, which journals the change. `human-request` is recorded only with a verbatim quote and a source; `agent-finding` and `agent-proposal` only with a source. Absent on flows created before the field existed and on flows whose evidence was not enough, and read as `unknown`. Gates nothing.",
+        properties: {
+          kind: { type: "string", enum: ["human-request", "agent-finding", "agent-proposal"] },
+          quote: {
+            type: "string",
+            description: "The human's request, verbatim and byte for byte: no translation, no paraphrase."
+          },
+          source: {
+            type: "string",
+            description: "Where the request or finding came from: channel, message id, time, or the check that produced it."
+          }
+        }
+      },
       signatures: {
         type: "array",
         description: "Append-only signing record for `flow ac confirm` and a passing `flow complete`. Absent means never signed under this field's existence.",
@@ -26845,17 +26994,24 @@ function outcomeBulletsFrom(markdown) {
   if (body === null)
     return null;
   const bullets = [];
+  let skipping = false;
   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)
+    if (bullet !== null) {
+      skipping = isOriginTemplateBullet(bullet[1] ?? "");
+      if (!skipping)
+        bullets.push((bullet[1] ?? "").trim());
+    } else if (line.trim().length > 0 && !skipping && bullets.length > 0)
       bullets[bullets.length - 1] += ` ${line.trim()}`;
   }
   return bullets.filter((bullet) => bullet.length > 0);
 }
+function isOriginTemplateBullet(text) {
+  const trimmed = text.trim();
+  return trimmed.startsWith(`${REQUEST_LABEL}:`) || trimmed.startsWith(`${SOURCE_LABEL}:`) || ORIGIN_PLACEHOLDER_BULLETS.some((placeholder) => placeholder.slice(2) === trimmed);
+}
 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;
@@ -27417,7 +27573,9 @@ async function flowFoldersInHead(cwd, dirs) {
 }
 
 // src/flow/templates.ts
-function renderDescription(title, source) {
+function renderDescription(title, source, origin) {
+  const outcome = origin === undefined ? OUTCOME_HINT : renderOriginBullets(origin).join(`
+`);
   return `# ${title}
 
 Status: draft (flow-init skill formalizes this)
@@ -27433,7 +27591,7 @@ What must be true when this flow is done.
 
 ## Outcome criteria
 
-${OUTCOME_HINT}
+${outcome}
 
 ## Out of Scope
 
@@ -27750,7 +27908,24 @@ function createFlowService(deps) {
       if (input.owner !== undefined && !input.owner.trim()) {
         throw new Error(BLANK_OWNER_MESSAGE);
       }
-      const outcomeAuthor = input.outcomeAuthor === undefined ? DEFAULT_OUTCOME_AUTHOR : parseOutcomeAuthor(input.outcomeAuthor);
+      const outcomeAuthor = input.outcomeAuthor === undefined ? undefined : parseOutcomeAuthor(input.outcomeAuthor);
+      let originNote;
+      let origin;
+      let originDraft;
+      if (input.origin !== undefined) {
+        const resolution = resolveOrigin({ kind: input.origin, quote: input.originQuote, source: input.originSource });
+        origin = resolution.origin;
+        originNote = resolution.note;
+        if (isOriginKind(input.origin)) {
+          originDraft = {
+            kind: input.origin,
+            ...input.originQuote?.trim() ? { quote: input.originQuote } : {},
+            ...input.originSource?.trim() ? { source: input.originSource } : {}
+          };
+        }
+      } else if (input.originQuote !== undefined || input.originSource !== undefined) {
+        originNote = "--quote/--source were given without --origin; origin stays unknown.";
+      }
       const trackerReady = deps.tracker ? await deps.tracker.detect() : false;
       const tracker = trackerReady ? deps.tracker : null;
       const issueRef = input.issue && deps.tracker ? deps.tracker.parseRef(input.issue) : null;
@@ -27806,12 +27981,13 @@ function createFlowService(deps) {
           pr: { url: null },
           ...input.baseBranch === undefined ? {} : { baseBranch: input.baseBranch },
           ...input.owner?.trim() ? { owner: ownerIdentity(input.owner.trim(), "`--owner` flag on `flow init`") } : {},
-          outcomeAuthor,
+          ...outcomeAuthor !== undefined ? { outcomeAuthor } : origin === undefined ? { outcomeAuthor: DEFAULT_OUTCOME_AUTHOR } : {},
+          ...origin === undefined ? {} : { origin },
           tasks: DEFAULT_TASKS.map((task) => ({ ...task, status: "todo" })),
           history: [{ at: createdAt, event: "created" }]
         };
         const sourceLabel = input.issue ?? "user description";
-        await writeFileAtomic(path56.join(absolute, "description.md"), renderDescription(title, sourceLabel));
+        await writeFileAtomic(path56.join(absolute, "description.md"), renderDescription(title, originDraft === undefined ? sourceLabel : `${sourceLabel} (origin: ${originDraft.kind})`, originDraft));
         await writeFileAtomic(path56.join(absolute, "context.md"), context.markdown);
         await writeFileAtomic(path56.join(absolute, "plan.md"), renderPlan());
         await writeFileAtomic(path56.join(absolute, "tasks.md"), renderTasksDoc());
@@ -27819,7 +27995,12 @@ function createFlowService(deps) {
         await writeFileAtomic(path56.join(absolute, "journal.md"), renderJournal(createdAt));
         await writeFlow(input.cwd, dir, flow);
         await recordAllocation(scope, { id, dir, at: createdAt, project: scope.project });
-        return { flow, dir: path56.relative(input.cwd, absolute), contextNotes: context.notes };
+        return {
+          flow,
+          dir: path56.relative(input.cwd, absolute),
+          contextNotes: context.notes,
+          ...originNote === undefined ? {} : { originNote }
+        };
       });
     },
     async list({ cwd }) {
@@ -27883,6 +28064,50 @@ function createFlowService(deps) {
       });
       return { flow, previous, changed };
     },
+    async originSet({ cwd, id, kind, reason, quote, source }) {
+      if (!reason?.trim()) {
+        throw new Error('flow origin set requires --reason "<why>"');
+      }
+      validateSingleLineReason(reason);
+      let previous = "unknown";
+      let next = "unknown";
+      let changed = false;
+      let note;
+      const flow = await mutate(cwd, id, async ({ dir, flow: current }) => {
+        const before = readOrigin(current.origin);
+        previous = before?.kind ?? "unknown";
+        let after;
+        if (kind !== "unknown" && !isOriginKind(kind)) {
+          note = `origin kind must be one of: human-request, agent-finding, agent-proposal, unknown (got "${kind}"); the origin is unchanged.`;
+          next = previous;
+          return current;
+        }
+        if (kind !== "unknown") {
+          const resolution = resolveOrigin({
+            kind,
+            quote: quote !== undefined && quote.length > 0 ? quote : before?.quote,
+            source: source !== undefined && source.length > 0 ? source : before?.source
+          });
+          if (resolution.origin === undefined) {
+            note = resolution.note;
+            next = previous;
+            return current;
+          }
+          after = resolution.origin;
+        }
+        next = after?.kind ?? "unknown";
+        if (JSON.stringify(before ?? null) === JSON.stringify(after ?? null)) {
+          return current;
+        }
+        changed = true;
+        if (after === undefined)
+          delete current.origin;
+        else
+          current.origin = after;
+        return save(cwd, dir, current, "origin-set", `${originSummary(before)} -> ${originSummary(after)} (${reason.trim()})`);
+      });
+      return { flow, previous, next, changed, ...note === undefined ? {} : { note } };
+    },
     async freeze({ cwd, id }) {
       return mutate(cwd, id, async ({ dir, flow }) => {
         assertTransition(flow.status, "ready");
@@ -41023,6 +41248,12 @@ var HELP_GROUPS = [
     group: "Managed work",
     summary: "List doc sections that likely went stale because of the working diff, with Jev."
   },
+  {
+    kind: "slash",
+    name: "/flow",
+    group: "Managed work",
+    summary: `Show a flow's origin, or set it with a reason \u2014 /flow origin [<id>] | /flow origin <id> <kind> --reason "...".`
+  },
   {
     kind: "slash",
     name: "/opencomments",
@@ -41082,7 +41313,7 @@ var HELP_GROUPS = [
     kind: "cli",
     name: "schedule",
     group: "Automation",
-    summary: "Scheduled agent tasks in the background: create (with confirmation), list, pause, resume, remove."
+    summary: "Scheduled agent tasks in the background: create (with confirmation), list, pause, resume, remove; `add --digest` makes a GitHub and board digest that `keryx serve` sends to Telegram."
   },
   {
     kind: "cli",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.57",
+  "version": "0.3.59",
   "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": {
@@ -49,7 +49,7 @@
     "test:client:terminal": "bun test src/tui/ src/commands/shell",
     "test:client:streaming": "bun test src/harness/provider/",
     "test:client:cancel-resume": "bun test src/harness/run/ src/harness/resume/ src/harness/session/ src/session/ src/bus/ src/rewind/ src/remote/ src/docs/ src/commands/sessions",
-    "test:client:runtime": "bun test src/harness/ src/mcp-client/ src/mcp-servers/ src/agents/ src/commands/agent src/commands/harness src/commands/providers",
+    "test:client:runtime": "bun test src/harness/ src/mcp-client/ src/mcp-servers/ src/agents/ src/commands/agent src/commands/harness src/commands/providers src/scheduler/",
     "test:client": "bun run test:client:terminal && bun run test:client:streaming && bun run test:client:cancel-resume && bun run test:client:runtime",
     "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",