kcode-pi 0.1.35 → 0.1.39

package/src/harness/question-memory.ts

@@ -0,0 +1,220 @@
+import type { ActiveRun, KdFact, KdQuestion } from "./types.ts";
+import { canonicalFactLabel } from "./prompt-policy.ts";
+
+export function formatQuestionMemory(run: ActiveRun): string {
+	const questions = Array.isArray(run.questions) ? run.questions : [];
+	const facts = currentFactsForRun(run);
+	const rejected = rejectedFactsForRun(run);
+	if (questions.length === 0 && facts.length === 0 && rejected.length === 0) return "无。";
+
+	const answered = questions.filter((question) => question.status === "answered");
+	const open = questions.filter((question) => question.status === "open");
+	const sections: string[] = [];
+
+	if (facts.length > 0) {
+		sections.push("## 当前结构化事实", formatCurrentFacts(run));
+	}
+	if (rejected.length > 0) {
+		sections.push("## 已否定候选事实", rejected.map((fact) => `- ${fact.label}：${fact.value}`).join("\n"));
+	}
+	if (answered.length > 0) {
+		sections.push("## 已回答问题", answered.map(formatAnsweredQuestion).join("\n"));
+	}
+	if (open.length > 0) {
+		sections.push("## 未回答问题", open.map(formatOpenQuestion).join("\n"));
+	}
+
+	return sections.join("\n\n") || "无。";
+}
+
+export function formatAnsweredQuestionFacts(run: ActiveRun): string {
+	return formatCurrentFacts(run);
+}
+
+export function formatCurrentFacts(run: ActiveRun): string {
+	const lines = currentFactsForRun(run).map((fact) => `- ${fact.label}：${fact.value}`);
+	return lines.length > 0 ? dedupe(lines).join("\n") : "无。";
+}
+
+export function currentFactsForRun(run: ActiveRun): KdFact[] {
+	return latestFactsByKey(persistedFactsForRun(run).filter((fact) => fact.status === "current" && fact.value.trim()));
+}
+
+export function rejectedFactsForRun(run: ActiveRun): KdFact[] {
+	return latestFactsByKey(persistedFactsForRun(run).filter((fact) => fact.status === "rejected" && fact.value.trim()));
+}
+
+export function currentFactForLabel(run: ActiveRun, label: string): KdFact | undefined {
+	const canonical = canonicalFactLabel(label) ?? label;
+	const key = factKey(canonical);
+	return currentFactsForRun(run).find((fact) => fact.key === key);
+}
+
+export function hasCurrentFactForLabel(run: ActiveRun, label: string): boolean {
+	return Boolean(currentFactForLabel(run, label));
+}
+
+export function factFromAnsweredQuestion(question: KdQuestion, now = new Date().toISOString()): KdFact | undefined {
+	if (question.status !== "answered" || !question.factLabel) return undefined;
+	const answer = question.answer?.trim();
+	if (!answer) return undefined;
+	if (isPlaceholderAnswer(answer)) return undefined;
+	const label = canonicalFactLabel(question.factLabel);
+	if (!label) return undefined;
+	if (question.proposedFactValue) {
+		if (!isAffirmativeOnlyAnswer(answer) && !isNegativeAnswer(answer)) return undefined;
+		const value = question.proposedFactValue.trim();
+		if (!value) return undefined;
+		return {
+			key: factKey(label),
+			label,
+			value,
+			status: isAffirmativeOnlyAnswer(answer) ? "current" : "rejected",
+			source: "question",
+			sourceQuestionId: question.id,
+			reason: question.reason,
+			createdAt: now,
+			updatedAt: now,
+		};
+	}
+
+	if (isConcreteAnswer(answer)) {
+		return {
+			key: factKey(label),
+			label,
+			value: answer,
+			status: "current",
+			source: "question",
+			sourceQuestionId: question.id,
+			reason: question.reason,
+			createdAt: now,
+			updatedAt: now,
+		};
+	}
+	return undefined;
+}
+
+export function questionAskBlockReason(run: ActiveRun, input: { factLabel?: string }): string | undefined {
+	const rawLabel = input.factLabel?.trim();
+	if (!rawLabel) return undefined;
+	const label = canonicalFactLabel(rawLabel);
+	if (!label) return `未知 factLabel：${rawLabel}。必须使用 KCode 集中定义的实现契约、数据源上下文或第三方对接事实标签。`;
+	const key = factKey(label);
+	const open = (Array.isArray(run.questions) ? run.questions : []).find(
+		(question) => question.status === "open" && question.blocking && question.factLabel && factKey(question.factLabel) === key,
+	);
+	if (open) {
+		return `事实标签 ${label} 已有未回答问题 ${open.id}，禁止重复提问。下一步：获取用户答案后用 kd_question action=answer id=${open.id} answer=<答案> 记录。`;
+	}
+	const fact = currentFactForLabel(run, label);
+	if (fact) {
+		return `事实标签 ${label} 已确认为 ${fact.value}，禁止重复提问。用户明确更正时使用 kd_question action=revise factLabel="${label}" answer="<新值>" reason="<更正原因>"。`;
+	}
+	return undefined;
+}
+
+export function invalidFactValueReason(value: string): string | undefined {
+	return isInvalidFactValue(value) ? "事实值不是可核验内容，不能使用待确认、未知、按实际环境、TODO/TBD、单独确认/否定或口头确认语解除门禁。" : undefined;
+}
+
+export function invalidConfirmationAnswerReason(value: string): string | undefined {
+	return isAffirmativeOnlyAnswer(value) || isNegativeAnswer(value) ? undefined : "确认题答案必须是明确肯定或明确否定，不能使用口头确认语或其他模糊回复。";
+}
+
+export function factKey(label: string): string {
+	return label.trim().toLowerCase().replace(/\s+/g, "");
+}
+
+export function upsertFact(facts: KdFact[] | undefined, next: KdFact): KdFact[] {
+	const existing = Array.isArray(facts) ? facts : [];
+	const now = next.updatedAt || new Date().toISOString();
+	const normalizedNext = { ...next, key: factKey(next.label), updatedAt: now, createdAt: next.createdAt || now };
+	const updated = existing.map((fact) => ({ ...fact }));
+
+	if (normalizedNext.status === "current") {
+		for (const fact of updated) {
+			if (fact.key === normalizedNext.key && fact.status === "current" && fact.value !== normalizedNext.value) {
+				fact.status = "superseded";
+				fact.updatedAt = now;
+				fact.supersededBy = normalizedNext.value;
+			}
+		}
+	}
+
+	const duplicate = updated.find(
+		(fact) =>
+			fact.key === normalizedNext.key &&
+			fact.value === normalizedNext.value &&
+			fact.status === normalizedNext.status &&
+			fact.sourceQuestionId === normalizedNext.sourceQuestionId,
+	);
+	if (duplicate) {
+		duplicate.updatedAt = now;
+		duplicate.reason = normalizedNext.reason ?? duplicate.reason;
+		return updated;
+	}
+
+	return [...updated, normalizedNext];
+}
+
+function isConcreteAnswer(answer: string): boolean {
+	return !isInvalidFactValue(answer);
+}
+
+function isAffirmativeOnlyAnswer(answer: string): boolean {
+	return /^(是|是的|对|正确|确认|yes|true)$/i.test(answer.trim());
+}
+
+function isNegativeAnswer(answer: string): boolean {
+	return /^(否|不是|不对|错误|no|false)(\s|。|，|,|；|;|$)/i.test(answer.trim());
+}
+
+function isPlaceholderAnswer(answer: string): boolean {
+	return /^(待确认|未知|不清楚|未提供|无|没有|none|unknown|todo|tbd|n\/a|按实际|按实际环境|以后再说)(\s|。|，|,|；|;|$)/i.test(answer.trim());
+}
+
+function isAcknowledgementOnlyAnswer(answer: string): boolean {
+	return /^(可以|好的|好|行|嗯|嗯嗯|收到|明白|ok|okay|行的)(\s|。|，|,|；|;|$)/i.test(answer.trim());
+}
+
+function isInvalidFactValue(answer: string): boolean {
+	return isPlaceholderAnswer(answer) || isAffirmativeOnlyAnswer(answer) || isNegativeAnswer(answer) || isAcknowledgementOnlyAnswer(answer);
+}
+
+function formatAnsweredQuestion(question: KdQuestion): string {
+	return `- ${question.id}：${question.question} => ${question.answer?.trim() ?? ""}`;
+}
+
+function formatOpenQuestion(question: KdQuestion): string {
+	return [
+		`- ${question.id}${question.blocking ? " [blocking]" : ""}：${question.question}`,
+		question.reason ? `  - 原因：${question.reason}` : undefined,
+		question.choices?.length ? `  - 选项：${question.choices.join(" | ")}` : undefined,
+	].filter(Boolean).join("\n");
+}
+
+function dedupe(values: string[]): string[] {
+	return [...new Set(values)];
+}
+
+function latestFactsByKey(facts: KdFact[]): KdFact[] {
+	const byKey = new Map<string, KdFact>();
+	for (const fact of facts) {
+		const current = byKey.get(fact.key);
+		if (!current || (fact.updatedAt || fact.createdAt).localeCompare(current.updatedAt || current.createdAt) >= 0) {
+			byKey.set(fact.key, fact);
+		}
+	}
+	return [...byKey.values()];
+}
+
+function persistedFactsForRun(run: ActiveRun): KdFact[] {
+	return (Array.isArray(run.facts) ? run.facts : []).flatMap(normalizePersistedFact);
+}
+
+function normalizePersistedFact(fact: KdFact): KdFact[] {
+	const label = canonicalFactLabel(fact.label);
+	const value = typeof fact.value === "string" ? fact.value.trim() : "";
+	if (!label || !value || invalidFactValueReason(value)) return [];
+	return [{ ...fact, key: factKey(label), label, value }];
+}

package/src/harness/repair.ts

@@ -40,6 +40,14 @@ export function recordVerifyResult(cwd: string, run: ActiveRun, input: VerifyRes
 	}
 
 	const normalized = normalizeInput(input);
+	const inputProblem = verifyInputBlockReason(normalized);
+	if (inputProblem) {
+		return {
+			status: "rejected",
+			run,
+			message: inputProblem,
+		};
+	}
 	if (normalized.exitCode === 0) {
 		return recordVerifyPass(cwd, run, normalized);
 	}
@@ -184,7 +192,7 @@ function formatVerifyEvidence(title: string, input: NormalizedVerifyResultInput)
 function normalizeInput(input: VerifyResultInput): NormalizedVerifyResultInput {
 	const exitCode = typeof input.exitCode === "number" ? input.exitCode : Number(input.exitCode);
 	return {
-		command: normalizeText(input.command).trim() || "unknown",
+		command: normalizeText(input.command).trim(),
 		exitCode: Number.isFinite(exitCode) ? Math.trunc(exitCode) : 1,
 		stdout: normalizeText(input.stdout),
 		stderr: normalizeText(input.stderr),
@@ -202,6 +210,13 @@ function verifyResultBlockReason(run: ActiveRun): string | undefined {
 	return `kd_verify_result 只能在 verify 阶段记录，或在自动修复循环的 execute 阶段记录。当前阶段：${run.phase}。`;
 }
 
+function verifyInputBlockReason(input: NormalizedVerifyResultInput): string | undefined {
+	if (!input.command || /^(unknown|待确认|未知|todo|tbd|n\/a)$/i.test(input.command)) {
+		return "kd_verify_result 缺少真实验证命令，拒绝记录证据。下一步：运行 PLAN.md 中声明的验证命令；外部系统或人工验证必须记录用户提供的命令、环境、测试数据和证据来源。";
+	}
+	return undefined;
+}
+
 function closeRepairQuestions(run: ActiveRun, evidence: string): void {
 	if (!Array.isArray(run.questions)) return;
 	const now = new Date().toISOString();

package/src/harness/state.ts

@@ -1,10 +1,12 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import type { ActiveRun, KdPhase, KdQuestion, KdRisk, KdRiskSource } from "./types.ts";
+import type { ActiveRun, KdFact, KdPhase, KdQuestion, KdRisk, KdRiskSource } from "./types.ts";
 import { PHASE_ARTIFACTS, isKdPhase, nextPhase } from "./types.ts";
 import { activeRunPath, kdDir, runStatePath, runsDir } from "./paths.ts";
 import { defaultArtifactContent, ensureArtifact, ensureRunDirectories, writeArtifact } from "./artifacts.ts";
 import { canEnterPhase, inspectGate } from "./gates.ts";
 import { profileForProduct, resolveProductProfile } from "../product/profile.ts";
+import { factFromAnsweredQuestion, factKey, invalidConfirmationAnswerReason, invalidFactValueReason, upsertFact } from "./question-memory.ts";
+import { canonicalFactLabel } from "./prompt-policy.ts";
 
 export function readActiveRun(cwd: string): ActiveRun | undefined {
 	const path = activeRunPath(cwd);
@@ -81,6 +83,7 @@ export function createActiveRun(cwd: string, goal: string, productInput?: string
 		profile,
 		artifacts: {},
 		questions: [],
+		facts: [],
 		gate: {
 			passed: false,
 			reason: "进入 spec 前必须完成 CONTEXT.md 并确认产品画像",
@@ -98,14 +101,25 @@ export function createActiveRun(cwd: string, goal: string, productInput?: string
 export function addQuestion(
 	cwd: string,
 	run: ActiveRun,
-	input: { question: string; reason?: string; choices?: string[]; blocking?: boolean },
+	input: { question: string; reason?: string; factLabel?: string; proposedFactValue?: string; choices?: string[]; blocking?: boolean },
 ): KdQuestion {
 	const existing = Array.isArray(run.questions) ? run.questions : [];
+	const canonicalLabel = input.factLabel?.trim() ? canonicalFactLabel(input.factLabel) : undefined;
+	const duplicate = existing.find(
+		(question) =>
+			question.status === "open" &&
+			question.blocking &&
+			((canonicalLabel && question.factLabel && factKey(question.factLabel) === factKey(canonicalLabel)) ||
+				normalizeQuestion(question.question) === normalizeQuestion(input.question)),
+	);
+	if (duplicate) return duplicate;
 	const question: KdQuestion = {
 		id: createQuestionId(existing.length + 1),
 		phase: run.phase,
 		question: input.question.trim(),
 		reason: input.reason?.trim() || undefined,
+		factLabel: canonicalLabel,
+		proposedFactValue: input.proposedFactValue?.trim() || undefined,
 		choices: input.choices?.map((choice) => choice.trim()).filter(Boolean),
 		blocking: input.blocking ?? true,
 		status: "open",
@@ -120,15 +134,49 @@ export function addQuestion(
 export function answerQuestion(cwd: string, run: ActiveRun, id: string, answer: string): KdQuestion | undefined {
 	const question = (Array.isArray(run.questions) ? run.questions : []).find((item) => item.id === id);
 	if (!question) return undefined;
+	if (question.status !== "open") return undefined;
+	const trimmed = answer.trim();
+	if (!trimmed) return undefined;
+	if (question.factLabel && question.proposedFactValue && invalidConfirmationAnswerReason(trimmed)) return undefined;
+	if (question.factLabel && !question.proposedFactValue && invalidFactValueReason(trimmed)) return undefined;
 	question.status = "answered";
-	question.answer = answer.trim();
+	question.answer = trimmed;
 	question.answeredAt = new Date().toISOString();
+	applyQuestionFact(run, question);
 	applyRepairQuestionAnswer(cwd, run, question);
 	run.gate = inspectGate(cwd, run);
 	writeActiveRun(cwd, run);
 	return question;
 }
 
+export function reviseFact(
+	cwd: string,
+	run: ActiveRun,
+	input: { factLabel: string; value: string; reason?: string },
+): KdFact | undefined {
+	const label = input.factLabel.trim();
+	const value = input.value.trim();
+	if (!label || !value) return undefined;
+	const canonicalLabel = canonicalFactLabel(label);
+	if (!canonicalLabel) return undefined;
+	if (invalidFactValueReason(value)) return undefined;
+	const now = new Date().toISOString();
+	const fact: KdFact = {
+		key: factKey(canonicalLabel),
+		label: canonicalLabel,
+		value,
+		status: "current",
+		source: "manual",
+		reason: input.reason?.trim() || undefined,
+		createdAt: now,
+		updatedAt: now,
+	};
+	run.facts = upsertFact(run.facts, fact);
+	run.gate = inspectGate(cwd, run);
+	writeActiveRun(cwd, run);
+	return fact;
+}
+
 export function openBlockingQuestions(run: ActiveRun): KdQuestion[] {
 	return (Array.isArray(run.questions) ? run.questions : []).filter((question) => question.status === "open" && question.blocking);
 }
@@ -217,6 +265,12 @@ function writeRunState(cwd: string, run: ActiveRun): void {
 	writeFileSync(runStatePath(cwd, run), `${JSON.stringify(run, null, 2)}\n`, "utf8");
 }
 
+function applyQuestionFact(run: ActiveRun, question: KdQuestion): void {
+	const fact = factFromAnsweredQuestion(question, question.answeredAt);
+	if (!fact) return;
+	run.facts = upsertFact(run.facts, fact);
+}
+
 function applyRepairQuestionAnswer(cwd: string, run: ActiveRun, question: KdQuestion): void {
 	if (!isRepairLimitQuestion(question)) return;
 	const answer = question.answer?.trim() ?? "";
@@ -280,13 +334,13 @@ function hydrateRun(parsed: ActiveRun): ActiveRun | undefined {
 	parsed.id = parsed.id.trim();
 	parsed.artifacts = isPlainObject(parsed.artifacts) ? sanitizeArtifacts(parsed.artifacts) : {};
 	parsed.questions = Array.isArray(parsed.questions) ? parsed.questions.map(sanitizeQuestion).filter((question): question is KdQuestion => Boolean(question)) : [];
+	parsed.facts = Array.isArray(parsed.facts) ? parsed.facts.map(sanitizeFact).filter((fact): fact is KdFact => Boolean(fact)) : [];
 	parsed.status = parsed.status === "paused" || parsed.status === "done" ? parsed.status : "active";
 	parsed.goal = typeof parsed.goal === "string" ? parsed.goal : undefined;
 	parsed.version = typeof parsed.version === "string" ? parsed.version : undefined;
 	parsed.createdAt = typeof parsed.createdAt === "string" ? parsed.createdAt : typeof parsed.updatedAt === "string" ? parsed.updatedAt : undefined;
 	parsed.updatedAt = typeof parsed.updatedAt === "string" ? parsed.updatedAt : parsed.createdAt;
-	const legacyEdition = (parsed as ActiveRun & { edition?: string }).edition;
-	const product = typeof parsed.profile?.product === "string" ? parsed.profile.product : typeof parsed.product === "string" ? parsed.product : resolveProductProfile(typeof legacyEdition === "string" ? legacyEdition : undefined).product;
+	const product = typeof parsed.profile?.product === "string" ? parsed.profile.product : typeof parsed.product === "string" ? parsed.product : resolveProductProfile(undefined).product;
 	parsed.profile = profileForProduct(product);
 	parsed.product = parsed.profile.product;
 	parsed.riskAssessment = sanitizeRiskAssessment(parsed.riskAssessment);
@@ -305,11 +359,15 @@ function sanitizeQuestion(value: unknown): KdQuestion | undefined {
 	const question = typeof value.question === "string" ? value.question.trim() : "";
 	if (!phase || !question) return undefined;
 	const id = typeof value.id === "string" && value.id.trim() ? value.id.trim() : createQuestionId(1);
+	const rawFactLabel = typeof value.factLabel === "string" && value.factLabel.trim() ? value.factLabel.trim() : undefined;
+	const factLabel = rawFactLabel ? canonicalFactLabel(rawFactLabel) : undefined;
 	return {
 		id,
 		phase,
 		question,
 		reason: typeof value.reason === "string" && value.reason.trim() ? value.reason.trim() : undefined,
+		factLabel,
+		proposedFactValue: typeof value.proposedFactValue === "string" && value.proposedFactValue.trim() ? value.proposedFactValue.trim() : undefined,
 		choices: Array.isArray(value.choices) ? value.choices.filter((choice): choice is string => typeof choice === "string" && Boolean(choice.trim())).map((choice) => choice.trim()) : undefined,
 		blocking: value.blocking !== false,
 		status: value.status === "answered" ? "answered" : "open",
@@ -319,6 +377,31 @@ function sanitizeQuestion(value: unknown): KdQuestion | undefined {
 	};
 }
 
+function sanitizeFact(value: unknown): KdFact | undefined {
+	if (!isPlainObject(value)) return undefined;
+	const label = typeof value.label === "string" ? value.label.trim() : "";
+	const factValue = typeof value.value === "string" ? value.value.trim() : "";
+	if (!label || !factValue) return undefined;
+	const canonicalLabel = canonicalFactLabel(label);
+	if (!canonicalLabel) return undefined;
+	if (invalidFactValueReason(factValue)) return undefined;
+	const status = value.status === "superseded" || value.status === "rejected" ? value.status : "current";
+	const source = value.source === "manual" ? "manual" : "question";
+	const now = new Date().toISOString();
+	return {
+		key: factKey(canonicalLabel),
+		label: canonicalLabel,
+		value: factValue,
+		status,
+		source,
+		sourceQuestionId: typeof value.sourceQuestionId === "string" && value.sourceQuestionId.trim() ? value.sourceQuestionId.trim() : undefined,
+		reason: typeof value.reason === "string" && value.reason.trim() ? value.reason.trim() : undefined,
+		createdAt: typeof value.createdAt === "string" ? value.createdAt : now,
+		updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : now,
+		supersededBy: typeof value.supersededBy === "string" && value.supersededBy.trim() ? value.supersededBy.trim() : undefined,
+	};
+}
+
 function sanitizeRiskAssessment(value: unknown): ActiveRun["riskAssessment"] {
 	if (!isPlainObject(value)) return undefined;
 	const level = value.level;
@@ -371,3 +454,7 @@ function createRunId(goal: string): string {
 function createQuestionId(sequence: number): string {
 	return `Q-${String(sequence).padStart(3, "0")}`;
 }
+
+function normalizeQuestion(question: string): string {
+	return question.trim().replace(/\s+/g, "").replace(/[?？。；;，,]/g, "");
+}

package/src/harness/types.ts

@@ -32,6 +32,8 @@ export interface KdQuestion {
 	phase: KdPhase;
 	question: string;
 	reason?: string;
+	factLabel?: string;
+	proposedFactValue?: string;
 	choices?: string[];
 	blocking: boolean;
 	status: "open" | "answered";
@@ -40,6 +42,22 @@ export interface KdQuestion {
 	answeredAt?: string;
 }
 
+export type KdFactStatus = "current" | "superseded" | "rejected";
+export type KdFactSource = "question" | "manual";
+
+export interface KdFact {
+	key: string;
+	label: string;
+	value: string;
+	status: KdFactStatus;
+	source: KdFactSource;
+	sourceQuestionId?: string;
+	reason?: string;
+	createdAt: string;
+	updatedAt: string;
+	supersededBy?: string;
+}
+
 export interface ActiveRun {
 	id: string;
 	goal?: string;
@@ -56,6 +74,7 @@ export interface ActiveRun {
 	artifacts: Record<string, string>;
 	gate: GateResult;
 	questions?: KdQuestion[];
+	facts?: KdFact[];
 }
 
 export const PHASE_ORDER: KdPhase[] = ["discuss", "spec", "plan", "execute", "verify", "ship"];