@mrciphersmith/keryx 0.3.58 → 0.3.59

package/dist/cli.js

@@ -20104,7 +20104,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@mrciphersmith/keryx",
-    version: "0.3.58",
+    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: {
@@ -56553,6 +56553,125 @@ var init_outcome_author = __esm(() => {
   OUTCOME_AUTHOR_READINGS = [...OUTCOME_AUTHORS, "unknown"];
 });
 
+// src/flow/origin.ts
+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;
+}
+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}`)];
+}
+var ORIGIN_KINDS, ORIGIN_READINGS, REQUEST_LABEL = "\u0417\u0430\u043F\u0440\u043E\u0441 (\u0434\u043E\u0441\u043B\u043E\u0432\u043D\u043E)", SOURCE_LABEL = "\u0418\u0441\u0442\u043E\u0447\u043D\u0438\u043A", 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)", 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)", REQUEST_PLACEHOLDER = "<the human's request, verbatim, no translation or paraphrase>", SOURCE_PLACEHOLDER = "<where the finding or proposal came from: check, review, test or discussion>", FORMALIZATION_PLACEHOLDER = "<the effect that has to be true when this flow is done, in your own words>", OBSERVE_PLACEHOLDER = "<how the effect can be observed once the flow is done>", ORIGIN_PLACEHOLDER_BULLETS;
+var init_origin = __esm(() => {
+  init_outcome_author();
+  ORIGIN_KINDS = ["human-request", "agent-finding", "agent-proposal"];
+  ORIGIN_READINGS = [...ORIGIN_KINDS, "unknown"];
+  ORIGIN_PLACEHOLDER_BULLETS = [
+    `- ${REQUEST_LABEL}: ${REQUEST_PLACEHOLDER}`,
+    `- ${SOURCE_LABEL}: ${SOURCE_PLACEHOLDER}`,
+    `- ${FORMALIZATION_LABEL}: ${FORMALIZATION_PLACEHOLDER}`,
+    `- ${OBSERVE_LABEL}: ${OBSERVE_PLACEHOLDER}`
+  ];
+});
+
 // src/flow/identity.ts
 function resolveSignerIdentity(input) {
   const stated = input.stated?.trim();
@@ -56999,6 +57118,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.",
@@ -57897,17 +58033,28 @@ 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);
+}
+function isOriginPlaceholderBullet(text) {
+  const trimmed = text.trim();
+  return ORIGIN_PLACEHOLDER_BULLETS.some((placeholder) => placeholder.slice(2) === trimmed);
+}
 function initIntentNote(description) {
   return flowStatementFrom(description) === null ? INIT_INTENT_NOTE : null;
 }
@@ -57920,6 +58067,7 @@ async function intentNoteForNewFlow(cwd, dir) {
 }
 var OUTCOME_HINT = 'State an outcome criterion: what you would look at afterwards to see this helped, as a bullet. Or write "- not measured \u2014 <reason>".', PLACEHOLDERS2, FLOW_STATEMENT_HEADINGS, STATEMENT_LIMIT = 300, INIT_INTENT_NOTE = "note: no intent statement extractable from description.md \u2014 the product index will hold no statement for this flow";
 var init_description_intent = __esm(() => {
+  init_origin();
   PLACEHOLDERS2 = ["Describe the problem precisely", "What must be true when this flow is done"];
   FLOW_STATEMENT_HEADINGS = [/^problem$/i, /^expected outcome$/i];
 });
@@ -58508,7 +58656,9 @@ var init_folder_committed = __esm(() => {
 });
 
 // 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)
@@ -58524,7 +58674,7 @@ What must be true when this flow is done.
 
 ## Outcome criteria
 
-${OUTCOME_HINT}
+${outcome}
 
 ## Out of Scope
 
@@ -58903,6 +59053,7 @@ whose status is \`implemented\`.
 var init_templates4 = __esm(() => {
   init_default_tasks();
   init_description_intent();
+  init_origin();
 });
 
 // src/flow/service.ts
@@ -58910,6 +59061,8 @@ var exports_service2 = {};
 __export(exports_service2, {
   AC_CHECK_TOKEN_BUDGET: () => AC_CHECK_TOKEN_BUDGET,
   CONFIRMATION_CAVEAT: () => CONFIRMATION_CAVEAT,
+  ORIGIN_KINDS: () => ORIGIN_KINDS,
+  ORIGIN_READINGS: () => ORIGIN_READINGS,
   OUTCOME_AUTHOR_READINGS: () => OUTCOME_AUTHOR_READINGS,
   REVIEW_GATE_CONFIG_PATH: () => REVIEW_GATE_CONFIG_PATH,
   acCheckCacheKey: () => acCheckCacheKey,
@@ -58924,6 +59077,7 @@ __export(exports_service2, {
   confirmPreconditionError: () => confirmPreconditionError,
   createFlowService: () => createFlowService,
   describeAcKind: () => describeAcKind,
+  effectiveOutcomeAuthor: () => effectiveOutcomeAuthor,
   evaluatedVerdict: () => evaluatedVerdict,
   extractCriterionTokens: () => extractCriterionTokens,
   factsOnlyVerdict: () => factsOnlyVerdict,
@@ -58933,6 +59087,7 @@ __export(exports_service2, {
   intentNoteForNewFlow: () => intentNoteForNewFlow,
   isFrozen: () => isFrozen,
   notCheckableVerdict: () => notCheckableVerdict,
+  originDetailLines: () => originDetailLines,
   outcomeBulletsFrom: () => outcomeBulletsFrom,
   parseAcceptanceCriteria: () => parseAcceptanceCriteria,
   proseOutsideFences: () => proseOutsideFences,
@@ -58940,7 +59095,8 @@ __export(exports_service2, {
   readAcCheckEnabled: () => readAcCheckEnabled,
   readAcKindRecords: () => readAcKindRecords,
   readFlow: () => readFlow,
-  readOutcomeAuthor: () => readOutcomeAuthor,
+  readOrigin: () => readOrigin,
+  readOriginKind: () => readOriginKind,
   renderAcCheckAdvisoryNotice: () => renderAcCheckAdvisoryNotice,
   renderAcCheckReport: () => renderAcCheckReport,
   renderAcKindDistribution: () => renderAcKindDistribution,
@@ -59203,7 +59359,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;
@@ -59259,12 +59432,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(path143.join(absolute, "description.md"), renderDescription(title, sourceLabel));
+        await writeFileAtomic(path143.join(absolute, "description.md"), renderDescription(title, originDraft === undefined ? sourceLabel : `${sourceLabel} (origin: ${originDraft.kind})`, originDraft));
         await writeFileAtomic(path143.join(absolute, "context.md"), context.markdown);
         await writeFileAtomic(path143.join(absolute, "plan.md"), renderPlan());
         await writeFileAtomic(path143.join(absolute, "tasks.md"), renderTasksDoc());
@@ -59272,7 +59446,12 @@ function createFlowService(deps) {
         await writeFileAtomic(path143.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: path143.relative(input.cwd, absolute), contextNotes: context.notes };
+        return {
+          flow,
+          dir: path143.relative(input.cwd, absolute),
+          contextNotes: context.notes,
+          ...originNote === undefined ? {} : { originNote }
+        };
       });
     },
     async list({ cwd }) {
@@ -59336,6 +59515,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");
@@ -60176,7 +60399,9 @@ var init_service9 = __esm(() => {
   init_machine();
   init_review_gate();
   init_outcome_author();
+  init_origin();
   init_outcome_author();
+  init_origin();
   init_flow_move();
   init_ac_reseal();
   init_schema3();
@@ -100970,6 +101195,12 @@ var init_help_groups = __esm(() => {
       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",
@@ -105351,6 +105582,8 @@ async function flowCommand(args) {
         return await runOwner(args.slice(1));
       case "outcome":
         return await runOutcome(args.slice(1));
+      case "origin":
+        return await runOrigin(args.slice(1));
       case "implemented":
         return await runImplemented(args.slice(1));
       case "complete":
@@ -105394,7 +105627,10 @@ async function runInit(args) {
     baseBranch: optionValue(args, "--base"),
     owner: optionValue(args, "--owner"),
     requireConfirmation: args.includes("--require-confirmation"),
-    outcomeAuthor: outcomeAuthorFlag(args)
+    outcomeAuthor: outcomeAuthorFlag(args),
+    origin: optionValue(args, "--origin"),
+    originQuote: textFlag(args, "--quote"),
+    originSource: textFlag(args, "--source")
   });
   banner("flow init", `Created flow ${result.flow.id}`);
   console.log(`  ${style.green(symbols.ok)} ${style.bold(result.flow.title)}`);
@@ -105404,7 +105640,12 @@ async function runInit(args) {
     console.log(`  base:   ${result.flow.baseBranch}`);
   }
   console.log(`  owner:  ${result.flow.owner?.value ?? style.dim("not set")}`);
-  console.log(`  outcome author: ${readOutcomeAuthor(result.flow.outcomeAuthor)}`);
+  console.log(`  outcome author: ${outcomeAuthorLine(result.flow)}`);
+  for (const line of originDetailLines(readOrigin(result.flow.origin), "  "))
+    console.log(line);
+  if (result.originNote !== undefined) {
+    console.log(`  ${style.yellow(WARN)} ${result.originNote}`);
+  }
   if (result.flow.gates?.confirmation) {
     console.log(`  confirmation: required ${style.dim("(a terminal-minted token: `keryx flow confirm <id>`)")}`);
   }
@@ -105423,6 +105664,18 @@ async function runInit(args) {
     `Freeze and start: ${style.cyan(`keryx flow freeze ${result.flow.id}`)} then ${style.cyan(`flow start ${result.flow.id}`)}.`
   ]);
 }
+function textFlag(args, name) {
+  const index = args.indexOf(name);
+  if (index >= 0) {
+    const next = args[index + 1];
+    return next !== undefined && !/^--[A-Za-z][\w-]*(=|$)/.test(next) ? next : undefined;
+  }
+  return args.find((argument) => argument.startsWith(`${name}=`))?.slice(name.length + 1);
+}
+function outcomeAuthorLine(flow) {
+  const reading = effectiveOutcomeAuthor(flow);
+  return flow.outcomeAuthor === undefined && reading !== "unknown" ? `${reading} (derived from origin)` : reading;
+}
 function outcomeAuthorFlag(args) {
   const given = args.filter((arg) => arg === "--outcome-author" || arg.startsWith("--outcome-author=")).length;
   if (given > 1) {
@@ -105545,7 +105798,9 @@ async function runStatus(args) {
   const acLabel = flow.acChecksum ? style.green("frozen") : style.yellow("not frozen");
   console.log(`  AC:      ${acLabel}, ${Object.keys(flow.acConfirmed).length} confirmed`);
   console.log(`  PR:      ${flow.pr.url ? style.cyan(flow.pr.url) : style.dim("none")}`);
-  console.log(`  outcome author: ${readOutcomeAuthor(flow.outcomeAuthor)}`);
+  console.log(`  outcome author: ${outcomeAuthorLine(flow)}`);
+  for (const line of originDetailLines(readOrigin(flow.origin), "  "))
+    console.log(line);
   console.log(`  owner:   ${flow.owner?.value ? `${flow.owner.value} ${style.dim(`[${flow.owner.basis}]`)}` : style.dim("not set")}`);
   const latestSignature = flow.signatures?.at(-1);
   console.log(`  signed:  ${latestSignature ? `${latestSignature.identity.value ?? "unknown"} ${style.dim(`[${latestSignature.identity.basis}]`)} ${style.dim(`(${latestSignature.kind}, ${latestSignature.at})`)}${latestSignature.confirmation ? ` ${style.dim(`+ terminal token ${latestSignature.confirmation.tokenRef}`)}` : ""}` : style.dim("no signatures yet")}`);
@@ -105814,9 +106069,43 @@ async function runOutcome(args) {
     author,
     reason: optionValue(rest, "--reason") ?? ""
   });
-  const after = readOutcomeAuthor(result.flow.outcomeAuthor);
+  const after = effectiveOutcomeAuthor(result.flow);
   console.log(result.changed ? `  ${style.green(symbols.ok)} Outcome author ${result.previous} ${style.cyan(symbols.arrow)} ${style.bold(after)}` : `  ${style.dim(symbols.bullet)} Outcome author already ${style.bold(after)}; nothing written`);
 }
+async function runOrigin(args) {
+  if (args[0] !== "set") {
+    throw new Error(ORIGIN_USAGE);
+  }
+  const rest = args.slice(1);
+  const positionals = [];
+  for (let i = 0;i < rest.length; i += 1) {
+    const arg = rest[i] ?? "";
+    if (arg === "--reason" || arg === "--quote" || arg === "--source") {
+      i += 1;
+    } else if (!arg.startsWith("--")) {
+      positionals.push(arg);
+    }
+  }
+  const id = positionals[0];
+  const kind = positionals[1];
+  if (!id || kind === undefined || positionals.length > 2) {
+    throw new Error(ORIGIN_USAGE);
+  }
+  const result = await getService().originSet({
+    cwd: process.cwd(),
+    id,
+    kind,
+    reason: optionValue(rest, "--reason") ?? "",
+    quote: textFlag(rest, "--quote"),
+    source: textFlag(rest, "--source")
+  });
+  if (result.note !== undefined) {
+    console.log(`  ${style.yellow(WARN)} ${result.note}`);
+    console.log(`  ${style.dim(symbols.bullet)} Origin stays ${style.bold(result.previous)}; nothing written`);
+    return;
+  }
+  console.log(result.changed ? `  ${style.green(symbols.ok)} Origin ${result.previous} ${style.cyan(symbols.arrow)} ${style.bold(result.next)}` : `  ${style.dim(symbols.bullet)} Origin already ${style.bold(result.next)}; nothing written`);
+}
 async function runAc(args) {
   const sub = args[0];
   if (sub === "confirm") {
@@ -106204,6 +106493,7 @@ function printHelp2() {
     'keryx flow task depends <id> <taskId> --on T1,T2|none --reason "<why>"   (repair an unsatisfiable dependsOn)',
     'keryx flow owner set <id> --owner "<name>" --reason "<why>"   (the human accountable; never inferred)',
     'keryx flow outcome author <id> agent|human --reason "<why>"   (who wrote the outcome criterion; journaled, gates nothing)',
+    'keryx flow origin set <id> human-request|agent-finding|agent-proposal|unknown --reason "<why>" [--quote "<verbatim>"] [--source "<ref>"]   (where the flow came from; journaled, gates nothing)',
     'keryx flow ac confirm <id> <ACn> [--note "<evidence>"] [--signed-by "<name>"]',
     'keryx flow ac update <id> --reason "<why>"   (re-freeze the file as already edited; VOIDS prior confirmations)',
     'keryx flow ac update <id> --criterion ACn --text "<criterion>" --reason "<why>"   (rewrite/append that one criterion, then re-freeze; VOIDS prior confirmations)',
@@ -106225,9 +106515,10 @@ function printHelp2() {
   ]);
   note("`--signed-by` names the signer explicitly (stated). Falls back to KERYX_ACTOR (also " + "stated), then to `git config user.email` in this checkout (derived \u2014 the person who " + "RAN the command, not necessarily who signed), then to `unknown`. None of these is proof a human signed: a flag, an environment variable, and a local git identity can all be set " + "by an agent. `--owner` is never inferred at all \u2014 see docs/decisions/keryx-harness/.");
   note("`flow init --outcome-author agent|human` records who wrote the outcome criterion: `agent` (the default when the flag " + "is absent) or `human`, and `human` only when the flag says so \u2014 never inferred from a git " + "identity, an owner or the environment. A flow without the field reads `unknown`. The flag labels a sample and gates nothing.");
+  note('`flow init --origin human-request|agent-finding|agent-proposal --quote "<verbatim>" --source "<ref>"` records where the flow came from. Evidence, not assertion: `human-request` is recorded only with a verbatim `--quote` of the human\'s first message with the idea AND a `--source` (channel, message id or time); `agent-finding` and `agent-proposal` need a `--source`. Without the evidence, or with an invalid kind, the origin stays `unknown`, the command still succeeds and says why. The Outcome criteria template then holds the request (or the source), the agent\'s formalization and how to observe it. `flow origin set` changes it later, with a reason. The origin labels a sample and gates nothing.');
   note("`flow confirm` mints a short-lived, single-use token only for a flow created with `--require-confirmation` (or `completion.require_confirmation: true`). " + CONFIRMATION_CAVEAT + " See docs/decisions/keryx-harness/TM-03-terminal-confirmation-token.md.");
 }
-var VALID_TASK_KINDS, WARN = "!", AC_CONFIRM_FLAGS, AC_UPDATE_FLAGS, AC_RESEAL_FLAGS, VALID_DISPOSITIONS, service4 = null, OUTCOME_AUTHOR_USAGE = 'Usage: keryx flow outcome author <id> agent|human --reason "<why>"', CHALLENGE_ALPHABET = "abcdefghjkmnpqrstuvwxyz23456789";
+var VALID_TASK_KINDS, WARN = "!", AC_CONFIRM_FLAGS, AC_UPDATE_FLAGS, AC_RESEAL_FLAGS, VALID_DISPOSITIONS, service4 = null, OUTCOME_AUTHOR_USAGE = 'Usage: keryx flow outcome author <id> agent|human --reason "<why>"', ORIGIN_USAGE = 'Usage: keryx flow origin set <id> human-request|agent-finding|agent-proposal|unknown --reason "<why>" [--quote "<verbatim>"] [--source "<ref>"]', CHALLENGE_ALPHABET = "abcdefghjkmnpqrstuvwxyz23456789";
 var init_flow = __esm(() => {
   init_args();
   init_fs();
@@ -106876,6 +107167,10 @@ function flowsInSession(flows, opts) {
     return explicitFlowMention(flow, text);
   });
 }
+function originField(raw) {
+  const origin = readOrigin(raw);
+  return origin === undefined ? {} : { origin };
+}
 function flowItemFromState(flow, dir) {
   const sessionIds = [
     ...new Set(flow.tasks.map((task) => task.runLink?.sessionId).filter((id) => typeof id === "string" && id.length > 0))
@@ -106894,7 +107189,8 @@ function flowItemFromState(flow, dir) {
     updatedAt: flow.updatedAt,
     source: flow.source.ref ?? flow.source.type,
     tasks: flow.tasks.map((task) => ({ id: task.id, title: task.title, status: task.status })),
-    outcomeAuthor: readOutcomeAuthor(flow.outcomeAuthor)
+    outcomeAuthor: effectiveOutcomeAuthor(flow),
+    ...originField(flow.origin)
   };
 }
 function localSacGuard() {
@@ -107123,6 +107419,7 @@ function formatFlowDetailLines(item) {
     `${item.id}  ${item.title}`,
     `Status   ${item.status}`,
     `Outcome author  ${item.outcomeAuthor ?? "unknown"}`,
+    ...originDetailLines(item.origin),
     ...item.interrupted ? [`         ${item.interrupted}`] : [],
     ...item.uncommitted ? [`         note: ${item.uncommitted}`] : [],
     ...(item.hygiene?.notes ?? []).map((note) => `         ${note}`),
@@ -107381,6 +107678,7 @@ function openFlows(otui, chrome, options) {
 }
 var FLOWS_COMMAND = "/flows", AC_COMMAND = "/ac", FLOWS_FOOTER, MARKER_GLYPH;
 var init_flow_inspector = __esm(() => {
+  init_service9();
   init_modal_host();
   init_ac_kinds_surface();
   init_inspector_sources();
@@ -107490,6 +107788,7 @@ function extractFlowIntent(source, repoPath) {
   const closed = status === "done";
   const title = text(flow.title) ?? /^#\s+(.+)$/m.exec(description)?.[1]?.trim() ?? repoPath.split("/").at(-1) ?? repoPath;
   const criterion = outcomeCriterionFrom(description) ?? outcomeCriterionFrom(source.criteria ?? "");
+  const origin = readOrigin(flow.origin);
   return {
     id: text(flow.id) ?? repoPath.split("/").at(-1)?.slice(0, 3) ?? repoPath,
     source: "flow",
@@ -107501,7 +107800,8 @@ function extractFlowIntent(source, repoPath) {
     flowStatus: status,
     closedAt: closed ? closedAtOf(flow) : null,
     outcome: { criterion, ...observationFrom(source.journal) },
-    outcomeAuthor: readOutcomeAuthor(flow.outcomeAuthor)
+    outcomeAuthor: effectiveOutcomeAuthor(flow),
+    ...origin === undefined ? {} : { origin }
   };
 }
 function extractDocpackIntent(source, repoPath) {
@@ -107717,6 +108017,32 @@ var init_corpus = __esm(() => {
   };
 });
 
+// src/product/by-origin.ts
+function g1aByOrigin(index) {
+  const criterion = new Map;
+  const notMeasured = new Map;
+  for (const intent of index.intents) {
+    if (intent.source !== "flow")
+      continue;
+    const reading = readOriginKind(intent.origin);
+    const bucket = hasInstrument(intent.outcome.criterion) ? criterion : notMeasured;
+    bucket.set(reading, (bucket.get(reading) ?? 0) + 1);
+  }
+  return ORIGIN_READINGS.map((origin) => ({ origin, criterion: criterion.get(origin) ?? 0, notMeasured: notMeasured.get(origin) ?? 0 }));
+}
+function g1aLines(rows) {
+  if (rows === undefined || rows.every((row) => row.criterion + row.notMeasured === 0))
+    return [];
+  return [
+    "G1a by origin (flows with a real criterion / not measured):",
+    ...rows.map((row) => `  ${row.origin}: ${row.criterion} real criterion, ${row.notMeasured} not measured`)
+  ];
+}
+var init_by_origin = __esm(() => {
+  init_service9();
+  init_extract3();
+});
+
 // src/product/store.ts
 import { readFile as readFile114 } from "fs/promises";
 import path242 from "path";
@@ -107775,6 +108101,13 @@ function indexProblem(value) {
       return "index.json holds an observed intent without a verdict";
     if (intent.outcomeAuthor !== undefined && !OUTCOME_AUTHOR_READINGS.includes(intent.outcomeAuthor))
       return "index.json holds an intent with an unknown outcome author";
+    if (intent.origin !== undefined) {
+      const origin = intent.origin;
+      if (!isRecord10(origin) || !ORIGIN_KINDS.includes(origin.kind))
+        return "index.json holds an intent with an unknown origin";
+      if (origin.quote !== undefined && typeof origin.quote !== "string" || origin.source !== undefined && typeof origin.source !== "string")
+        return "index.json holds an intent with an unusable origin";
+    }
   }
   return null;
 }
@@ -107826,7 +108159,9 @@ function buildOpenReport(index) {
     closedAt: intent.closedAt,
     outcome: hasInstrument(intent.outcome.criterion) ? intent.outcome.criterion : intent.outcome.criterion ?? NO_INSTRUMENT,
     hasCriterion: hasInstrument(intent.outcome.criterion),
-    outcomeAuthor: readOutcomeAuthor(intent.outcomeAuthor)
+    outcomeAuthor: effectiveOutcomeAuthor({ outcomeAuthor: intent.outcomeAuthor, origin: intent.origin }),
+    origin: readOriginKind(intent.origin),
+    ...originFields(intent.origin)
   })).sort((a, b) => (b.closedAt ?? "").localeCompare(a.closedAt ?? "") || Number.parseInt(b.id, 10) - Number.parseInt(a.id, 10) || (a.path < b.path ? -1 : 1));
   const { counts } = index;
   return {
@@ -107840,7 +108175,15 @@ function buildOpenReport(index) {
     harmed: counts.harmed,
     inconclusive: counts.inconclusive,
     failures: index.failures.length,
-    entries
+    entries,
+    g1a: g1aByOrigin(index)
+  };
+}
+function originFields(raw) {
+  const origin = readOrigin(raw);
+  return {
+    ...origin?.quote === undefined ? {} : { originQuote: origin.quote },
+    ...origin?.source === undefined ? {} : { originSource: origin.source }
   };
 }
 function openHeaderLines(report) {
@@ -107862,12 +108205,14 @@ function openEntryLines(entry) {
     `${label}  ${entry.title}`,
     `${pad}outcome: ${entry.outcome}`,
     `${pad}outcome author: ${entry.outcomeAuthor}`,
+    ...originDetailLines(entry.origin === undefined || entry.origin === "unknown" ? undefined : { kind: entry.origin, quote: entry.originQuote, source: entry.originSource }, pad),
     `${pad}closed ${entry.closedAt === null ? "at an unrecorded time" : entry.closedAt.slice(0, 10)}`
   ];
 }
 function renderOpen(report) {
   const rows = report.entries.flatMap((entry) => ["", ...openEntryLines(entry).map((line) => `  ${line}`)]);
-  return [...openHeaderLines(report), ...rows].join(`
+  const g1a = g1aLines(report.g1a);
+  return [...openHeaderLines(report), ...rows, ...g1a.length > 0 ? ["", ...g1a] : []].join(`
 `);
 }
 async function loadOpenReport(cwd) {
@@ -107900,6 +108245,7 @@ function renderIndexSummary(index, file) {
 var REBUILD = "Run `keryx product index`.";
 var init_open = __esm(() => {
   init_service9();
+  init_by_origin();
   init_extract3();
   init_store7();
 });
@@ -107908,6 +108254,7 @@ var init_open = __esm(() => {
 var init_service14 = __esm(() => {
   init_corpus();
   init_extract3();
+  init_by_origin();
   init_open();
   init_store7();
 });
@@ -115426,6 +115773,11 @@ var init_agent_commands = __esm(() => {
       description: "List doc sections that likely went stale because of the working diff, with Jev",
       modes: AGENT_ONLY
     },
+    {
+      name: "/flow",
+      description: `Show a flow's origin, or set it \u2014 /flow origin [<id>] | /flow origin <id> <kind> --reason "..."`,
+      modes: AGENT_ONLY
+    },
     {
       name: "/opencomments",
       description: "List open PR review comments with a Jev resolved/still-open/escalation label \u2014 /opencomments <owner/repo> <pr>",
@@ -115852,12 +116204,25 @@ function proseEntries(body) {
   const entries = [];
   let sawHint = false;
   let open = false;
+  let skippingOrigin = false;
   for (const raw of body.split(/\r?\n/)) {
     const line = raw.trim();
     if (line.length === 0) {
       open = false;
       continue;
     }
+    if (/^[-*]\s+/.test(line)) {
+      const text = line.replace(/^[-*]\s+/, "");
+      skippingOrigin = isOriginTemplateBullet(text);
+      if (skippingOrigin) {
+        if (isOriginPlaceholderBullet(text))
+          sawHint = true;
+        open = false;
+        continue;
+      }
+    } else if (skippingOrigin && /^\s+\S/.test(raw)) {
+      continue;
+    }
     const unquoted = line.replace(/^>\s*/, "").replace(/^[-*]\s+/, "");
     if (unquoted === OUTCOME_HINT) {
       sawHint = true;
@@ -129625,6 +129990,115 @@ var init_jev_scenarios_command = __esm(() => {
   init_scope();
 });
 
+// src/tui/flow-origin-command.ts
+function isFlowOriginCommand(name) {
+  return name === FLOW_ORIGIN_COMMAND;
+}
+function splitShellWords(line) {
+  const words = [];
+  let current = "";
+  let quote;
+  let started = false;
+  for (const char of line) {
+    if (quote !== undefined) {
+      if (char === quote)
+        quote = undefined;
+      else
+        current += char;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      started = true;
+    } else if (/\s/.test(char)) {
+      if (started || current.length > 0)
+        words.push(current);
+      current = "";
+      started = false;
+    } else {
+      current += char;
+      started = true;
+    }
+  }
+  if (started || current.length > 0)
+    words.push(current);
+  return words;
+}
+function parseOriginArgs(words) {
+  const parsed = { positionals: [] };
+  for (let i = 0;i < words.length; i += 1) {
+    const word = words[i] ?? "";
+    if (word === "--reason" || word === "--quote" || word === "--source") {
+      const value = words[i + 1];
+      i += 1;
+      if (word === "--reason")
+        parsed.reason = value;
+      else if (word === "--quote")
+        parsed.quote = value;
+      else
+        parsed.source = value;
+    } else {
+      parsed.positionals.push(word);
+    }
+  }
+  return parsed;
+}
+function renderFlowOrigin(id, origin) {
+  return [`${id}`, ...originDetailLines(readOrigin(origin), "  ")].join(`
+`);
+}
+async function runFlowOriginForShell(cwd, line, service = createFlowService(flowServiceDeps())) {
+  const words = splitShellWords(line.trim());
+  const [, sub, ...rest] = words;
+  if (sub !== "origin") {
+    return `Usage: ${FLOW_ORIGIN_USAGE}`;
+  }
+  const args = parseOriginArgs(rest);
+  const [id, kind, ...extra] = args.positionals;
+  if (extra.length > 0) {
+    return `Usage: ${FLOW_ORIGIN_USAGE}`;
+  }
+  if (id === undefined) {
+    const flows = await service.list({ cwd });
+    if (flows.length === 0)
+      return "No flows.";
+    const blocks = [];
+    for (const summary of flows) {
+      const flow = await service.get({ cwd, id: summary.id });
+      blocks.push(renderFlowOrigin(flow.id, flow.origin));
+    }
+    return blocks.join(`
+`);
+  }
+  if (kind === undefined) {
+    const flow = await service.get({ cwd, id });
+    return renderFlowOrigin(flow.id, flow.origin);
+  }
+  if (args.reason === undefined || args.reason.trim().length === 0) {
+    return `/flow origin ${id} ${kind} needs --reason "<why>".
+Usage: ${FLOW_ORIGIN_USAGE}`;
+  }
+  const result = await service.originSet({
+    cwd,
+    id,
+    kind,
+    reason: args.reason,
+    quote: args.quote,
+    source: args.source
+  });
+  if (result.note !== undefined) {
+    return `${result.note}
+Nothing written; origin stays ${result.previous}.
+${renderFlowOrigin(result.flow.id, result.flow.origin)}`;
+  }
+  const head = result.changed ? `origin ${result.previous} -> ${result.next}` : `origin already ${result.next}; nothing written`;
+  return `${head}
+${renderFlowOrigin(result.flow.id, result.flow.origin)}`;
+}
+var FLOW_ORIGIN_COMMAND = "/flow", FLOW_ORIGIN_USAGE = '/flow origin [<id>]  |  /flow origin <id> <kind> --reason "<why>" [--quote "<verbatim>"] [--source "<ref>"]  (kind: human-request, agent-finding, agent-proposal, unknown)';
+var init_flow_origin_command = __esm(() => {
+  init_flow();
+  init_service9();
+});
+
 // src/review/jev-docs-config.ts
 import { readFile as readFile138 } from "fs/promises";
 import path277 from "path";
@@ -150959,6 +151433,19 @@ ${formatThemeList(getThemeId())}`);
 `);
             } catch (error) {
               io.onSystem?.(`review-jev-docs: ${error instanceof Error ? error.message : String(error)}
+`);
+            }
+          });
+          return;
+        }
+        if (isFlowOriginCommand(command.name)) {
+          const cwd = inspectorCwd();
+          trackCommandWork(async () => {
+            try {
+              io.onSystem?.(`${await runFlowOriginForShell(cwd, line)}
+`);
+            } catch (error) {
+              io.onSystem?.(`flow origin: ${error instanceof Error ? error.message : String(error)}
 `);
             }
           });
@@ -151888,6 +152375,7 @@ var init_tui_shell = __esm(() => {
   init_jev_contract_command();
   init_jev_triage_command();
   init_jev_scenarios_command();
+  init_flow_origin_command();
   init_jev_docs_command();
   init_jev_comments_command();
   init_ci_triage_source();
@@ -177285,7 +177773,7 @@ var init_command_registry = __esm(() => {
     {
       module: "tasks",
       command: "flow status",
-      summary: "One flow's full status: lifecycle state, outcome author (agent, human or unknown), AC freeze/confirmation count, PR, owner, latest signature, task list, and recent history.",
+      summary: "One flow's full status: lifecycle state, outcome author (agent, human or unknown), origin (kind, quote, source), AC freeze/confirmation count, PR, owner, latest signature, task list, and recent history.",
       intent: ["\u0441\u0442\u0430\u0442\u0443\u0441 \u0444\u043B\u043E\u0443", "flow status", "flow details", "show one flow"],
       args: [{ name: "<id>", type: "string", required: true, desc: "flow id" }],
       json: false,
@@ -177294,7 +177782,7 @@ var init_command_registry = __esm(() => {
     {
       module: "tasks",
       command: "flow init",
-      summary: "Create a new flow (managed work item): allocates an id, scaffolds its directory, and collects initial " + "context from the source issue if one is given. `--owner` is NEVER inferred \u2014 only an explicit value " + "on this command populates it. `--outcome-author` records who wrote the outcome criterion (default " + "`agent`; `human` only when the flag says so).",
+      summary: "Create a new flow (managed work item): allocates an id, scaffolds its directory, and collects initial " + "context from the source issue if one is given. `--owner` is NEVER inferred \u2014 only an explicit value " + "on this command populates it. `--outcome-author` records who wrote the outcome criterion (default " + "`agent`; `human` only when the flag says so). `--origin` records where the flow came from, with the " + "evidence its kind needs (`human-request`: a verbatim `--quote` and a `--source`; `agent-finding` and " + "`agent-proposal`: a `--source`); without it the origin stays `unknown`.",
       intent: ["\u0441\u043E\u0437\u0434\u0430\u0439 \u0444\u043B\u043E\u0443", "flow init", "start a new flow", "new managed work item", "\u0437\u0430\u0432\u0435\u0434\u0438 \u0444\u043B\u043E\u0443"],
       args: [
         { name: "title", type: "string", required: false, desc: "work title; required unless --issue is given" },
@@ -177313,7 +177801,15 @@ var init_command_registry = __esm(() => {
           type: "string",
           required: false,
           desc: "who wrote the outcome criterion: agent (the default when omitted) or human; never inferred, any other value is refused before the flow is created; gates nothing"
-        }
+        },
+        {
+          name: "origin",
+          type: "string",
+          required: false,
+          desc: "where the flow came from: human-request, agent-finding or agent-proposal; recorded only with its evidence, otherwise it stays unknown and the command still succeeds; an invalid kind is reported and ignored; gates nothing"
+        },
+        { name: "quote", type: "string", required: false, desc: "the human's request, verbatim and byte for byte (required with --origin human-request)" },
+        { name: "source", type: "string", required: false, desc: "where the request or finding came from: channel, message id, time or check (required with every --origin kind)" }
       ],
       json: false,
       read: false,
@@ -177350,6 +177846,22 @@ var init_command_registry = __esm(() => {
       read: false,
       sideEffects: ["writes flow.json's outcomeAuthor field and appends one journal.md line and a history entry"]
     },
+    {
+      module: "tasks",
+      command: "flow origin set",
+      summary: "Change where a flow came from (human-request, agent-finding, agent-proposal, or unknown to clear it). Requires a reason; " + "the evidence rule applies (a verbatim quote and a source for human-request, a source for the agent kinds), and without it " + "nothing is written and the reason is printed. Appends one journal line naming the old origin, the new one and the reason. " + "Works on any flow, never changes the outcome author, gates nothing.",
+      intent: ["\u043E\u0442\u043A\u0443\u0434\u0430 \u043F\u0440\u0438\u0448\u0451\u043B \u0444\u043B\u043E\u0443", "flow origin set", "set flow origin", "mark flow as human request", "\u043F\u0440\u043E\u0438\u0441\u0445\u043E\u0436\u0434\u0435\u043D\u0438\u0435 \u0444\u043B\u043E\u0443"],
+      args: [
+        { name: "<id>", type: "string", required: true, desc: "flow id" },
+        { name: "<kind>", type: "string", required: true, desc: "human-request, agent-finding, agent-proposal or unknown" },
+        { name: "reason", type: "string", required: true, desc: "why the origin is being set or changed; one line" },
+        { name: "quote", type: "string", required: false, desc: "the human's request, verbatim; kept from the flow when omitted" },
+        { name: "source", type: "string", required: false, desc: "channel, message id, time or check; kept from the flow when omitted" }
+      ],
+      json: false,
+      read: false,
+      sideEffects: ["writes flow.json's origin field and appends one journal.md line and a history entry"]
+    },
     {
       module: "tasks",
       command: "flow ac confirm",
@@ -205542,6 +206054,7 @@ var init_group_subcommands = __esm(() => {
         "check-ac",
         "owner",
         "outcome",
+        "origin",
         "implemented",
         "complete",
         "check-complete",

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

package/package.json

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