@kitsy/coop-ai 1.0.0 → 2.1.0

package/dist/index.cjs

@@ -30,18 +30,24 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  buildIdeaRefinementPrompt: () => buildIdeaRefinementPrompt,
+  buildTaskRefinementPrompt: () => buildTaskRefinementPrompt,
   build_contract: () => build_contract,
   build_decomposition_prompt: () => build_decomposition_prompt,
   constraint_violation_reasons: () => constraint_violation_reasons,
   create_provider: () => create_provider,
   create_provider_agent_client: () => create_provider_agent_client,
   create_provider_idea_decomposer: () => create_provider_idea_decomposer,
+  create_provider_refinement_client: () => create_provider_refinement_client,
   create_run: () => create_run,
   decompose_idea_to_tasks: () => decompose_idea_to_tasks,
   enforce_constraints: () => enforce_constraints,
   execute_task: () => execute_task,
   finalize_run: () => finalize_run,
   log_step: () => log_step,
+  parseRefinementDraftResponse: () => parseRefinementDraftResponse,
+  refine_idea_to_draft: () => refine_idea_to_draft,
+  refine_task_to_draft: () => refine_task_to_draft,
   resolve_provider_config: () => resolve_provider_config,
   select_agent: () => select_agent,
   validate_command: () => validate_command,
@@ -101,6 +107,17 @@ function taskAcceptance(task) {
   const maybe = asRecord(task).acceptance;
   return asStringArray(maybe) ?? [];
 }
+function taskTestsRequired(task) {
+  const maybe = asRecord(task).tests_required;
+  return asStringArray(maybe) ?? [];
+}
+function taskOriginRefs(task) {
+  const origin = asRecord(asRecord(task).origin);
+  return {
+    authority_refs: asStringArray(origin.authority_refs) ?? [],
+    derived_refs: asStringArray(origin.derived_refs) ?? []
+  };
+}
 function collectRelatedArtifacts(task, graph) {
   const context = asRecord(task.execution?.context ?? {});
   const relatedTaskIds = dedupe(asStringArray(context.tasks) ?? []);
@@ -195,9 +212,12 @@ function build_contract(task, graph, config) {
   const taskContextFiles = asStringArray(executionContext.files) ?? [];
   const taskContextTasks = asStringArray(executionContext.tasks) ?? [];
   const acceptance_criteria = taskAcceptance(task);
+  const tests_required = taskTestsRequired(task);
+  const origin_refs = taskOriginRefs(task);
   const related_task_artifacts = collectRelatedArtifacts(task, graph);
   const output_requirements = [
     ...DEFAULT_OUTPUT_REQUIREMENTS,
+    ...tests_required.length > 0 ? tests_required.map((entry) => `Required test: ${entry}`) : [],
     ...(task.artifacts?.produces ?? []).map((artifact) => {
       if (artifact.path) {
         return `Produce ${artifact.type} artifact at ${artifact.path}`;
@@ -229,6 +249,9 @@ function build_contract(task, graph, config) {
       files: taskContextFiles,
       tasks: taskContextTasks,
       acceptance_criteria,
+      tests_required,
+      authority_refs: origin_refs.authority_refs,
+      derived_refs: origin_refs.derived_refs,
       related_task_artifacts
     },
     output_requirements
@@ -628,7 +651,7 @@ function build_decomposition_prompt(input) {
   return [
     "You are a planning agent for COOP.",
     "Decompose the idea into 2-5 implementation tasks.",
-    "Each task needs: title, type(feature|bug|chore|spike), priority(p0-p3), and body.",
+    "Each task needs: title, type(feature|bug|chore|spike), priority(p0-p3), body, acceptance_criteria, and tests_required.",
     `Idea ID: ${input.idea_id}`,
     `Title: ${input.title}`,
     "Body:",
@@ -647,6 +670,259 @@ async function decompose_idea_to_tasks(input, client) {
   return drafts;
 }
 
+// src/refinement/refine.ts
+function sentenceCase2(value) {
+  if (value.length === 0) return value;
+  return `${value[0]?.toUpperCase() ?? ""}${value.slice(1)}`;
+}
+function nonEmptyLines2(input) {
+  return input.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+function extractBulletIdeas2(body) {
+  return nonEmptyLines2(body).filter((line) => /^[-*]\s+/.test(line)).map((line) => line.replace(/^[-*]\s+/, "").trim()).filter(Boolean).slice(0, 5);
+}
+function taskBodySections(title) {
+  return [
+    "## Objective",
+    title,
+    "",
+    "## Scope",
+    "- Define implementation boundaries",
+    "",
+    "## Constraints",
+    "- Preserve existing behavior unless explicitly changed",
+    "",
+    "## References",
+    "- Add source refs during refinement/apply",
+    "",
+    "## Refinement Notes",
+    "- Generated by COOP refinement fallback"
+  ].join("\n");
+}
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) return void 0;
+  const entries = value.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean);
+  return entries.length > 0 ? entries : void 0;
+}
+function normalizeProposal(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const record = value;
+  const title = typeof record.title === "string" ? record.title.trim() : "";
+  if (!title) return null;
+  const action = record.action === "update" ? "update" : "create";
+  return {
+    action,
+    id: typeof record.id === "string" && record.id.trim() ? record.id.trim() : void 0,
+    target_id: typeof record.target_id === "string" && record.target_id.trim() ? record.target_id.trim() : void 0,
+    title,
+    type: record.type === "feature" || record.type === "bug" || record.type === "chore" || record.type === "spike" || record.type === "epic" ? record.type : void 0,
+    status: record.status === "todo" || record.status === "blocked" || record.status === "in_progress" || record.status === "in_review" || record.status === "done" || record.status === "canceled" ? record.status : void 0,
+    track: typeof record.track === "string" ? record.track.trim() || void 0 : void 0,
+    priority: record.priority === "p0" || record.priority === "p1" || record.priority === "p2" || record.priority === "p3" ? record.priority : void 0,
+    depends_on: normalizeStringArray(record.depends_on),
+    acceptance: normalizeStringArray(record.acceptance),
+    tests_required: normalizeStringArray(record.tests_required),
+    authority_refs: normalizeStringArray(record.authority_refs),
+    derived_refs: normalizeStringArray(record.derived_refs),
+    body: typeof record.body === "string" ? record.body : void 0
+  };
+}
+function normalizeDraft(value, mode, sourceId, sourceTitle) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const record = value;
+  const proposalsRaw = Array.isArray(record.proposals) ? record.proposals : Array.isArray(record.tasks) ? record.tasks : [];
+  const proposals = proposalsRaw.map((entry) => normalizeProposal(entry)).filter((entry) => Boolean(entry));
+  if (proposals.length === 0) return null;
+  const summary = typeof record.summary === "string" && record.summary.trim() ? record.summary.trim() : `Refined ${mode} ${sourceId}`;
+  return {
+    kind: "refinement_draft",
+    version: 1,
+    mode,
+    source: {
+      entity_type: mode,
+      id: sourceId,
+      title: sourceTitle
+    },
+    summary,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    proposals
+  };
+}
+function parseJsonObject(text) {
+  const trimmed = text.trim();
+  const candidates = [trimmed];
+  const fenced = trimmed.match(/```json\s*([\s\S]*?)```/i);
+  if (fenced?.[1]) {
+    candidates.push(fenced[1]);
+  }
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    candidates.push(trimmed.slice(start, end + 1));
+  }
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function fallbackIdeaRefinement(input) {
+  const bullets = extractBulletIdeas2(input.body);
+  const tasks = bullets.length > 0 ? bullets.slice(0, 3).map((bullet, index) => ({
+    title: sentenceCase2(bullet),
+    body: taskBodySections(sentenceCase2(bullet)),
+    type: index === 0 ? "spike" : "feature",
+    priority: index === 0 ? "p1" : "p2",
+    track: "unassigned",
+    acceptance_criteria: [`${sentenceCase2(bullet)} is implemented as described`],
+    tests_required: ["Relevant integration or regression coverage is added"]
+  })) : [
+    {
+      title: `Define scope and acceptance for ${input.title}`,
+      body: taskBodySections(`Define scope and acceptance for ${input.title}`),
+      type: "spike",
+      priority: "p1",
+      track: "unassigned",
+      acceptance_criteria: [`Scope and acceptance are explicit for ${input.title}`],
+      tests_required: ["Planning review recorded"]
+    },
+    {
+      title: `Implement ${input.title}`,
+      body: taskBodySections(`Implement ${input.title}`),
+      type: "feature",
+      priority: "p1",
+      track: "unassigned",
+      acceptance_criteria: [`${input.title} is implemented end-to-end`],
+      tests_required: ["Automated test coverage added for the primary path"]
+    }
+  ];
+  return {
+    kind: "refinement_draft",
+    version: 1,
+    mode: "idea",
+    source: {
+      entity_type: "idea",
+      id: input.idea_id,
+      title: input.title
+    },
+    summary: `Refined idea ${input.idea_id} into ${tasks.length} proposed task(s).`,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    proposals: tasks.map((task) => ({
+      action: "create",
+      title: task.title,
+      type: task.type,
+      status: "todo",
+      track: task.track ?? "unassigned",
+      priority: task.priority,
+      acceptance: task.acceptance_criteria,
+      tests_required: task.tests_required,
+      body: task.body
+    }))
+  };
+}
+function fallbackTaskRefinement(input) {
+  const authorityRefs = input.task.origin?.authority_refs ?? [];
+  const derivedRefs = input.task.origin?.derived_refs ?? [];
+  const acceptance = input.task.acceptance && input.task.acceptance.length > 0 ? input.task.acceptance : [`${input.task.title} is complete and reviewable against its defined scope`];
+  const testsRequired = input.task.tests_required && input.task.tests_required.length > 0 ? input.task.tests_required : ["Automated regression coverage for the changed behavior"];
+  return {
+    kind: "refinement_draft",
+    version: 1,
+    mode: "task",
+    source: {
+      entity_type: "task",
+      id: input.task.id,
+      title: input.task.title
+    },
+    summary: `Refined task ${input.task.id} into an execution-ready update proposal.`,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    proposals: [
+      {
+        action: "update",
+        target_id: input.task.id,
+        title: input.task.title,
+        type: input.task.type,
+        status: input.task.status,
+        track: input.task.track,
+        priority: input.task.priority,
+        depends_on: input.task.depends_on,
+        acceptance,
+        tests_required: testsRequired,
+        authority_refs: authorityRefs,
+        derived_refs: derivedRefs,
+        body: input.body?.trim() || taskBodySections(input.task.title)
+      }
+    ]
+  };
+}
+function buildIdeaRefinementPrompt(input) {
+  return [
+    "You are a COOP planning agent.",
+    "Return ONLY JSON object with keys: summary, proposals.",
+    "proposals must be an array of task proposals.",
+    "Each proposal must include: action(create), title, type(feature|bug|chore|spike), priority(p0-p3), track, acceptance(string[]), tests_required(string[]), body.",
+    "Use depends_on only for existing task ids when necessary.",
+    `Idea ID: ${input.idea_id}`,
+    `Title: ${input.title}`,
+    "Body:",
+    input.body || "(empty)",
+    input.supplemental_context?.trim() ? ["Supplemental Context:", input.supplemental_context].join("\n") : ""
+  ].filter(Boolean).join("\n");
+}
+function buildTaskRefinementPrompt(input) {
+  const authorityContext = (input.authority_context ?? []).map((entry) => `Ref: ${entry.ref}
+${entry.content}`).join("\n\n---\n\n");
+  return [
+    "You are a COOP planning/refinement agent.",
+    "Return ONLY JSON object with keys: summary, proposals.",
+    "proposals must be an array with one update proposal for the current task.",
+    "The proposal must include: action(update), target_id, title, type, status, track, priority, depends_on, acceptance(string[]), tests_required(string[]), authority_refs(string[]), derived_refs(string[]), body.",
+    `Task ID: ${input.task.id}`,
+    `Title: ${input.task.title}`,
+    `Status: ${input.task.status}`,
+    `Type: ${input.task.type}`,
+    `Priority: ${input.task.priority ?? "p2"}`,
+    `Track: ${input.task.track ?? "unassigned"}`,
+    `Depends On: ${(input.task.depends_on ?? []).join(", ") || "-"}`,
+    "Task Body:",
+    input.body || "(empty)",
+    authorityContext ? ["Authority Context:", authorityContext].join("\n") : "",
+    input.supplemental_context?.trim() ? ["Supplemental Context:", input.supplemental_context].join("\n") : ""
+  ].filter(Boolean).join("\n");
+}
+async function refine_idea_to_draft(input, client) {
+  const prompt = buildIdeaRefinementPrompt(input);
+  if (!client) {
+    return fallbackIdeaRefinement(input);
+  }
+  const result = await client.refineIdea(prompt, input);
+  return result ?? fallbackIdeaRefinement(input);
+}
+async function refine_task_to_draft(input, client) {
+  const prompt = buildTaskRefinementPrompt(input);
+  if (!client) {
+    return fallbackTaskRefinement(input);
+  }
+  const result = await client.refineTask(prompt, input);
+  return result ?? fallbackTaskRefinement(input);
+}
+function parseRefinementDraftResponse(text, mode, sourceId, sourceTitle) {
+  const parsed = parseJsonObject(text);
+  if (!parsed) {
+    return null;
+  }
+  return normalizeDraft(parsed, mode, sourceId, sourceTitle);
+}
+
 // src/providers/config.ts
 var DEFAULT_MODELS = {
   openai: "gpt-5-mini",
@@ -978,6 +1254,12 @@ function toTaskDrafts(value) {
   }
   return out;
 }
+function refinementSystemPrompt(mode) {
+  if (mode === "idea") {
+    return "Return ONLY JSON object with keys summary and proposals. proposals must be an array of task proposals with action(create), title, type, priority, track, acceptance, tests_required, body.";
+  }
+  return "Return ONLY JSON object with keys summary and proposals. proposals must be an array with one update proposal containing action(update), target_id, title, type, status, track, priority, depends_on, acceptance, tests_required, authority_refs, derived_refs, body.";
+}
 function asAgentResponse(text, tokens) {
   return {
     summary: text.trim(),
@@ -1019,20 +1301,45 @@ function create_provider_idea_decomposer(config) {
     }
   };
 }
+function create_provider_refinement_client(config) {
+  const provider = create_provider(config);
+  return {
+    async refineIdea(prompt, input) {
+      const result = await provider.complete({
+        system: refinementSystemPrompt("idea"),
+        prompt
+      });
+      return parseRefinementDraftResponse(result.text, "idea", input.idea_id, input.title);
+    },
+    async refineTask(prompt, input) {
+      const result = await provider.complete({
+        system: refinementSystemPrompt("task"),
+        prompt
+      });
+      return parseRefinementDraftResponse(result.text, "task", input.task.id, input.task.title);
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  buildIdeaRefinementPrompt,
+  buildTaskRefinementPrompt,
   build_contract,
   build_decomposition_prompt,
   constraint_violation_reasons,
   create_provider,
   create_provider_agent_client,
   create_provider_idea_decomposer,
+  create_provider_refinement_client,
   create_run,
   decompose_idea_to_tasks,
   enforce_constraints,
   execute_task,
   finalize_run,
   log_step,
+  parseRefinementDraftResponse,
+  refine_idea_to_draft,
+  refine_task_to_draft,
   resolve_provider_config,
   select_agent,
   validate_command,

package/dist/index.d.cts

@@ -25,6 +25,9 @@ interface AgentContractContext {
     files: string[];
     tasks: string[];
     acceptance_criteria: string[];
+    tests_required: string[];
+    authority_refs: string[];
+    derived_refs: string[];
     related_task_artifacts: AgentContractRelatedArtifacts[];
 }
 interface AgentContract {
@@ -141,6 +144,8 @@ interface DecomposedTaskDraft {
     type?: "feature" | "bug" | "chore" | "spike";
     priority?: "p0" | "p1" | "p2" | "p3";
     track?: string;
+    acceptance_criteria?: string[];
+    tests_required?: string[];
 }
 interface IdeaDecomposerClient {
     decompose(prompt: string, input: IdeaDecompositionInput): Promise<DecomposedTaskDraft[]>;
@@ -156,6 +161,61 @@ declare function build_decomposition_prompt(input: IdeaDecompositionInput): stri
  */
 declare function decompose_idea_to_tasks(input: IdeaDecompositionInput, client?: IdeaDecomposerClient): Promise<DecomposedTaskDraft[]>;
 
+type RefinementProposalAction = "create" | "update";
+interface RefinementTaskProposal {
+    action: RefinementProposalAction;
+    id?: string;
+    target_id?: string;
+    title: string;
+    type?: Task["type"];
+    status?: Task["status"];
+    track?: string;
+    priority?: "p0" | "p1" | "p2" | "p3";
+    depends_on?: string[];
+    acceptance?: string[];
+    tests_required?: string[];
+    authority_refs?: string[];
+    derived_refs?: string[];
+    body?: string;
+}
+interface RefinementDraft {
+    kind: "refinement_draft";
+    version: 1;
+    mode: "idea" | "task";
+    source: {
+        entity_type: "idea" | "task";
+        id: string;
+        title: string;
+    };
+    summary: string;
+    generated_at: string;
+    proposals: RefinementTaskProposal[];
+}
+interface IdeaRefinementInput {
+    idea_id: string;
+    title: string;
+    body: string;
+    supplemental_context?: string;
+}
+interface TaskRefinementInput {
+    task: Task;
+    body: string;
+    supplemental_context?: string;
+    authority_context?: Array<{
+        ref: string;
+        content: string;
+    }>;
+}
+interface RefinementClient {
+    refineIdea(prompt: string, input: IdeaRefinementInput): Promise<RefinementDraft | null>;
+    refineTask(prompt: string, input: TaskRefinementInput): Promise<RefinementDraft | null>;
+}
+declare function buildIdeaRefinementPrompt(input: IdeaRefinementInput): string;
+declare function buildTaskRefinementPrompt(input: TaskRefinementInput): string;
+declare function refine_idea_to_draft(input: IdeaRefinementInput, client?: RefinementClient): Promise<RefinementDraft>;
+declare function refine_task_to_draft(input: TaskRefinementInput, client?: RefinementClient): Promise<RefinementDraft>;
+declare function parseRefinementDraftResponse(text: string, mode: "idea" | "task", sourceId: string, sourceTitle: string): RefinementDraft | null;
+
 type AiProviderName = "mock" | "openai" | "anthropic" | "gemini" | "ollama";
 interface ProviderConfig {
     provider: AiProviderName;
@@ -201,5 +261,6 @@ declare function create_provider_agent_client(config: unknown): AgentClient;
  * [SPEC: Architecture v2.0 §Phase 4]
  */
 declare function create_provider_idea_decomposer(config: unknown): IdeaDecomposerClient;
+declare function create_provider_refinement_client(config: unknown): RefinementClient;
 
-export { type AgentClient, type AgentContract, type AgentContractConstraints, type AgentContractContext, type AgentContractPermissions, type AgentContractRelatedArtifacts, type AgentResponse, type AiProviderName, type CompletionInput, type CompletionResult, type DecomposedTaskDraft, type ExecuteTaskOptions, type FileAccessMode, type IdeaDecomposerClient, type IdeaDecompositionInput, type LlmProvider, type ProviderConfig, type RunResult, type SandboxRunState, build_contract, build_decomposition_prompt, constraint_violation_reasons, create_provider, create_provider_agent_client, create_provider_idea_decomposer, create_run, decompose_idea_to_tasks, enforce_constraints, execute_task, finalize_run, log_step, resolve_provider_config, select_agent, validate_command, validate_file_access, write_run };
+export { type AgentClient, type AgentContract, type AgentContractConstraints, type AgentContractContext, type AgentContractPermissions, type AgentContractRelatedArtifacts, type AgentResponse, type AiProviderName, type CompletionInput, type CompletionResult, type DecomposedTaskDraft, type ExecuteTaskOptions, type FileAccessMode, type IdeaDecomposerClient, type IdeaDecompositionInput, type IdeaRefinementInput, type LlmProvider, type ProviderConfig, type RefinementClient, type RefinementDraft, type RefinementProposalAction, type RefinementTaskProposal, type RunResult, type SandboxRunState, type TaskRefinementInput, buildIdeaRefinementPrompt, buildTaskRefinementPrompt, build_contract, build_decomposition_prompt, constraint_violation_reasons, create_provider, create_provider_agent_client, create_provider_idea_decomposer, create_provider_refinement_client, create_run, decompose_idea_to_tasks, enforce_constraints, execute_task, finalize_run, log_step, parseRefinementDraftResponse, refine_idea_to_draft, refine_task_to_draft, resolve_provider_config, select_agent, validate_command, validate_file_access, write_run };

package/dist/index.d.ts

@@ -25,6 +25,9 @@ interface AgentContractContext {
     files: string[];
     tasks: string[];
     acceptance_criteria: string[];
+    tests_required: string[];
+    authority_refs: string[];
+    derived_refs: string[];
     related_task_artifacts: AgentContractRelatedArtifacts[];
 }
 interface AgentContract {
@@ -141,6 +144,8 @@ interface DecomposedTaskDraft {
     type?: "feature" | "bug" | "chore" | "spike";
     priority?: "p0" | "p1" | "p2" | "p3";
     track?: string;
+    acceptance_criteria?: string[];
+    tests_required?: string[];
 }
 interface IdeaDecomposerClient {
     decompose(prompt: string, input: IdeaDecompositionInput): Promise<DecomposedTaskDraft[]>;
@@ -156,6 +161,61 @@ declare function build_decomposition_prompt(input: IdeaDecompositionInput): stri
  */
 declare function decompose_idea_to_tasks(input: IdeaDecompositionInput, client?: IdeaDecomposerClient): Promise<DecomposedTaskDraft[]>;
 
+type RefinementProposalAction = "create" | "update";
+interface RefinementTaskProposal {
+    action: RefinementProposalAction;
+    id?: string;
+    target_id?: string;
+    title: string;
+    type?: Task["type"];
+    status?: Task["status"];
+    track?: string;
+    priority?: "p0" | "p1" | "p2" | "p3";
+    depends_on?: string[];
+    acceptance?: string[];
+    tests_required?: string[];
+    authority_refs?: string[];
+    derived_refs?: string[];
+    body?: string;
+}
+interface RefinementDraft {
+    kind: "refinement_draft";
+    version: 1;
+    mode: "idea" | "task";
+    source: {
+        entity_type: "idea" | "task";
+        id: string;
+        title: string;
+    };
+    summary: string;
+    generated_at: string;
+    proposals: RefinementTaskProposal[];
+}
+interface IdeaRefinementInput {
+    idea_id: string;
+    title: string;
+    body: string;
+    supplemental_context?: string;
+}
+interface TaskRefinementInput {
+    task: Task;
+    body: string;
+    supplemental_context?: string;
+    authority_context?: Array<{
+        ref: string;
+        content: string;
+    }>;
+}
+interface RefinementClient {
+    refineIdea(prompt: string, input: IdeaRefinementInput): Promise<RefinementDraft | null>;
+    refineTask(prompt: string, input: TaskRefinementInput): Promise<RefinementDraft | null>;
+}
+declare function buildIdeaRefinementPrompt(input: IdeaRefinementInput): string;
+declare function buildTaskRefinementPrompt(input: TaskRefinementInput): string;
+declare function refine_idea_to_draft(input: IdeaRefinementInput, client?: RefinementClient): Promise<RefinementDraft>;
+declare function refine_task_to_draft(input: TaskRefinementInput, client?: RefinementClient): Promise<RefinementDraft>;
+declare function parseRefinementDraftResponse(text: string, mode: "idea" | "task", sourceId: string, sourceTitle: string): RefinementDraft | null;
+
 type AiProviderName = "mock" | "openai" | "anthropic" | "gemini" | "ollama";
 interface ProviderConfig {
     provider: AiProviderName;
@@ -201,5 +261,6 @@ declare function create_provider_agent_client(config: unknown): AgentClient;
  * [SPEC: Architecture v2.0 §Phase 4]
  */
 declare function create_provider_idea_decomposer(config: unknown): IdeaDecomposerClient;
+declare function create_provider_refinement_client(config: unknown): RefinementClient;
 
-export { type AgentClient, type AgentContract, type AgentContractConstraints, type AgentContractContext, type AgentContractPermissions, type AgentContractRelatedArtifacts, type AgentResponse, type AiProviderName, type CompletionInput, type CompletionResult, type DecomposedTaskDraft, type ExecuteTaskOptions, type FileAccessMode, type IdeaDecomposerClient, type IdeaDecompositionInput, type LlmProvider, type ProviderConfig, type RunResult, type SandboxRunState, build_contract, build_decomposition_prompt, constraint_violation_reasons, create_provider, create_provider_agent_client, create_provider_idea_decomposer, create_run, decompose_idea_to_tasks, enforce_constraints, execute_task, finalize_run, log_step, resolve_provider_config, select_agent, validate_command, validate_file_access, write_run };
+export { type AgentClient, type AgentContract, type AgentContractConstraints, type AgentContractContext, type AgentContractPermissions, type AgentContractRelatedArtifacts, type AgentResponse, type AiProviderName, type CompletionInput, type CompletionResult, type DecomposedTaskDraft, type ExecuteTaskOptions, type FileAccessMode, type IdeaDecomposerClient, type IdeaDecompositionInput, type IdeaRefinementInput, type LlmProvider, type ProviderConfig, type RefinementClient, type RefinementDraft, type RefinementProposalAction, type RefinementTaskProposal, type RunResult, type SandboxRunState, type TaskRefinementInput, buildIdeaRefinementPrompt, buildTaskRefinementPrompt, build_contract, build_decomposition_prompt, constraint_violation_reasons, create_provider, create_provider_agent_client, create_provider_idea_decomposer, create_provider_refinement_client, create_run, decompose_idea_to_tasks, enforce_constraints, execute_task, finalize_run, log_step, parseRefinementDraftResponse, refine_idea_to_draft, refine_task_to_draft, resolve_provider_config, select_agent, validate_command, validate_file_access, write_run };

package/dist/index.js

@@ -49,6 +49,17 @@ function taskAcceptance(task) {
   const maybe = asRecord(task).acceptance;
   return asStringArray(maybe) ?? [];
 }
+function taskTestsRequired(task) {
+  const maybe = asRecord(task).tests_required;
+  return asStringArray(maybe) ?? [];
+}
+function taskOriginRefs(task) {
+  const origin = asRecord(asRecord(task).origin);
+  return {
+    authority_refs: asStringArray(origin.authority_refs) ?? [],
+    derived_refs: asStringArray(origin.derived_refs) ?? []
+  };
+}
 function collectRelatedArtifacts(task, graph) {
   const context = asRecord(task.execution?.context ?? {});
   const relatedTaskIds = dedupe(asStringArray(context.tasks) ?? []);
@@ -143,9 +154,12 @@ function build_contract(task, graph, config) {
   const taskContextFiles = asStringArray(executionContext.files) ?? [];
   const taskContextTasks = asStringArray(executionContext.tasks) ?? [];
   const acceptance_criteria = taskAcceptance(task);
+  const tests_required = taskTestsRequired(task);
+  const origin_refs = taskOriginRefs(task);
   const related_task_artifacts = collectRelatedArtifacts(task, graph);
   const output_requirements = [
     ...DEFAULT_OUTPUT_REQUIREMENTS,
+    ...tests_required.length > 0 ? tests_required.map((entry) => `Required test: ${entry}`) : [],
     ...(task.artifacts?.produces ?? []).map((artifact) => {
       if (artifact.path) {
         return `Produce ${artifact.type} artifact at ${artifact.path}`;
@@ -177,6 +191,9 @@ function build_contract(task, graph, config) {
       files: taskContextFiles,
       tasks: taskContextTasks,
       acceptance_criteria,
+      tests_required,
+      authority_refs: origin_refs.authority_refs,
+      derived_refs: origin_refs.derived_refs,
       related_task_artifacts
     },
     output_requirements
@@ -576,7 +593,7 @@ function build_decomposition_prompt(input) {
   return [
     "You are a planning agent for COOP.",
     "Decompose the idea into 2-5 implementation tasks.",
-    "Each task needs: title, type(feature|bug|chore|spike), priority(p0-p3), and body.",
+    "Each task needs: title, type(feature|bug|chore|spike), priority(p0-p3), body, acceptance_criteria, and tests_required.",
     `Idea ID: ${input.idea_id}`,
     `Title: ${input.title}`,
     "Body:",
@@ -595,6 +612,259 @@ async function decompose_idea_to_tasks(input, client) {
   return drafts;
 }
 
+// src/refinement/refine.ts
+function sentenceCase2(value) {
+  if (value.length === 0) return value;
+  return `${value[0]?.toUpperCase() ?? ""}${value.slice(1)}`;
+}
+function nonEmptyLines2(input) {
+  return input.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+function extractBulletIdeas2(body) {
+  return nonEmptyLines2(body).filter((line) => /^[-*]\s+/.test(line)).map((line) => line.replace(/^[-*]\s+/, "").trim()).filter(Boolean).slice(0, 5);
+}
+function taskBodySections(title) {
+  return [
+    "## Objective",
+    title,
+    "",
+    "## Scope",
+    "- Define implementation boundaries",
+    "",
+    "## Constraints",
+    "- Preserve existing behavior unless explicitly changed",
+    "",
+    "## References",
+    "- Add source refs during refinement/apply",
+    "",
+    "## Refinement Notes",
+    "- Generated by COOP refinement fallback"
+  ].join("\n");
+}
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) return void 0;
+  const entries = value.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean);
+  return entries.length > 0 ? entries : void 0;
+}
+function normalizeProposal(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const record = value;
+  const title = typeof record.title === "string" ? record.title.trim() : "";
+  if (!title) return null;
+  const action = record.action === "update" ? "update" : "create";
+  return {
+    action,
+    id: typeof record.id === "string" && record.id.trim() ? record.id.trim() : void 0,
+    target_id: typeof record.target_id === "string" && record.target_id.trim() ? record.target_id.trim() : void 0,
+    title,
+    type: record.type === "feature" || record.type === "bug" || record.type === "chore" || record.type === "spike" || record.type === "epic" ? record.type : void 0,
+    status: record.status === "todo" || record.status === "blocked" || record.status === "in_progress" || record.status === "in_review" || record.status === "done" || record.status === "canceled" ? record.status : void 0,
+    track: typeof record.track === "string" ? record.track.trim() || void 0 : void 0,
+    priority: record.priority === "p0" || record.priority === "p1" || record.priority === "p2" || record.priority === "p3" ? record.priority : void 0,
+    depends_on: normalizeStringArray(record.depends_on),
+    acceptance: normalizeStringArray(record.acceptance),
+    tests_required: normalizeStringArray(record.tests_required),
+    authority_refs: normalizeStringArray(record.authority_refs),
+    derived_refs: normalizeStringArray(record.derived_refs),
+    body: typeof record.body === "string" ? record.body : void 0
+  };
+}
+function normalizeDraft(value, mode, sourceId, sourceTitle) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const record = value;
+  const proposalsRaw = Array.isArray(record.proposals) ? record.proposals : Array.isArray(record.tasks) ? record.tasks : [];
+  const proposals = proposalsRaw.map((entry) => normalizeProposal(entry)).filter((entry) => Boolean(entry));
+  if (proposals.length === 0) return null;
+  const summary = typeof record.summary === "string" && record.summary.trim() ? record.summary.trim() : `Refined ${mode} ${sourceId}`;
+  return {
+    kind: "refinement_draft",
+    version: 1,
+    mode,
+    source: {
+      entity_type: mode,
+      id: sourceId,
+      title: sourceTitle
+    },
+    summary,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    proposals
+  };
+}
+function parseJsonObject(text) {
+  const trimmed = text.trim();
+  const candidates = [trimmed];
+  const fenced = trimmed.match(/```json\s*([\s\S]*?)```/i);
+  if (fenced?.[1]) {
+    candidates.push(fenced[1]);
+  }
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    candidates.push(trimmed.slice(start, end + 1));
+  }
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function fallbackIdeaRefinement(input) {
+  const bullets = extractBulletIdeas2(input.body);
+  const tasks = bullets.length > 0 ? bullets.slice(0, 3).map((bullet, index) => ({
+    title: sentenceCase2(bullet),
+    body: taskBodySections(sentenceCase2(bullet)),
+    type: index === 0 ? "spike" : "feature",
+    priority: index === 0 ? "p1" : "p2",
+    track: "unassigned",
+    acceptance_criteria: [`${sentenceCase2(bullet)} is implemented as described`],
+    tests_required: ["Relevant integration or regression coverage is added"]
+  })) : [
+    {
+      title: `Define scope and acceptance for ${input.title}`,
+      body: taskBodySections(`Define scope and acceptance for ${input.title}`),
+      type: "spike",
+      priority: "p1",
+      track: "unassigned",
+      acceptance_criteria: [`Scope and acceptance are explicit for ${input.title}`],
+      tests_required: ["Planning review recorded"]
+    },
+    {
+      title: `Implement ${input.title}`,
+      body: taskBodySections(`Implement ${input.title}`),
+      type: "feature",
+      priority: "p1",
+      track: "unassigned",
+      acceptance_criteria: [`${input.title} is implemented end-to-end`],
+      tests_required: ["Automated test coverage added for the primary path"]
+    }
+  ];
+  return {
+    kind: "refinement_draft",
+    version: 1,
+    mode: "idea",
+    source: {
+      entity_type: "idea",
+      id: input.idea_id,
+      title: input.title
+    },
+    summary: `Refined idea ${input.idea_id} into ${tasks.length} proposed task(s).`,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    proposals: tasks.map((task) => ({
+      action: "create",
+      title: task.title,
+      type: task.type,
+      status: "todo",
+      track: task.track ?? "unassigned",
+      priority: task.priority,
+      acceptance: task.acceptance_criteria,
+      tests_required: task.tests_required,
+      body: task.body
+    }))
+  };
+}
+function fallbackTaskRefinement(input) {
+  const authorityRefs = input.task.origin?.authority_refs ?? [];
+  const derivedRefs = input.task.origin?.derived_refs ?? [];
+  const acceptance = input.task.acceptance && input.task.acceptance.length > 0 ? input.task.acceptance : [`${input.task.title} is complete and reviewable against its defined scope`];
+  const testsRequired = input.task.tests_required && input.task.tests_required.length > 0 ? input.task.tests_required : ["Automated regression coverage for the changed behavior"];
+  return {
+    kind: "refinement_draft",
+    version: 1,
+    mode: "task",
+    source: {
+      entity_type: "task",
+      id: input.task.id,
+      title: input.task.title
+    },
+    summary: `Refined task ${input.task.id} into an execution-ready update proposal.`,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    proposals: [
+      {
+        action: "update",
+        target_id: input.task.id,
+        title: input.task.title,
+        type: input.task.type,
+        status: input.task.status,
+        track: input.task.track,
+        priority: input.task.priority,
+        depends_on: input.task.depends_on,
+        acceptance,
+        tests_required: testsRequired,
+        authority_refs: authorityRefs,
+        derived_refs: derivedRefs,
+        body: input.body?.trim() || taskBodySections(input.task.title)
+      }
+    ]
+  };
+}
+function buildIdeaRefinementPrompt(input) {
+  return [
+    "You are a COOP planning agent.",
+    "Return ONLY JSON object with keys: summary, proposals.",
+    "proposals must be an array of task proposals.",
+    "Each proposal must include: action(create), title, type(feature|bug|chore|spike), priority(p0-p3), track, acceptance(string[]), tests_required(string[]), body.",
+    "Use depends_on only for existing task ids when necessary.",
+    `Idea ID: ${input.idea_id}`,
+    `Title: ${input.title}`,
+    "Body:",
+    input.body || "(empty)",
+    input.supplemental_context?.trim() ? ["Supplemental Context:", input.supplemental_context].join("\n") : ""
+  ].filter(Boolean).join("\n");
+}
+function buildTaskRefinementPrompt(input) {
+  const authorityContext = (input.authority_context ?? []).map((entry) => `Ref: ${entry.ref}
+${entry.content}`).join("\n\n---\n\n");
+  return [
+    "You are a COOP planning/refinement agent.",
+    "Return ONLY JSON object with keys: summary, proposals.",
+    "proposals must be an array with one update proposal for the current task.",
+    "The proposal must include: action(update), target_id, title, type, status, track, priority, depends_on, acceptance(string[]), tests_required(string[]), authority_refs(string[]), derived_refs(string[]), body.",
+    `Task ID: ${input.task.id}`,
+    `Title: ${input.task.title}`,
+    `Status: ${input.task.status}`,
+    `Type: ${input.task.type}`,
+    `Priority: ${input.task.priority ?? "p2"}`,
+    `Track: ${input.task.track ?? "unassigned"}`,
+    `Depends On: ${(input.task.depends_on ?? []).join(", ") || "-"}`,
+    "Task Body:",
+    input.body || "(empty)",
+    authorityContext ? ["Authority Context:", authorityContext].join("\n") : "",
+    input.supplemental_context?.trim() ? ["Supplemental Context:", input.supplemental_context].join("\n") : ""
+  ].filter(Boolean).join("\n");
+}
+async function refine_idea_to_draft(input, client) {
+  const prompt = buildIdeaRefinementPrompt(input);
+  if (!client) {
+    return fallbackIdeaRefinement(input);
+  }
+  const result = await client.refineIdea(prompt, input);
+  return result ?? fallbackIdeaRefinement(input);
+}
+async function refine_task_to_draft(input, client) {
+  const prompt = buildTaskRefinementPrompt(input);
+  if (!client) {
+    return fallbackTaskRefinement(input);
+  }
+  const result = await client.refineTask(prompt, input);
+  return result ?? fallbackTaskRefinement(input);
+}
+function parseRefinementDraftResponse(text, mode, sourceId, sourceTitle) {
+  const parsed = parseJsonObject(text);
+  if (!parsed) {
+    return null;
+  }
+  return normalizeDraft(parsed, mode, sourceId, sourceTitle);
+}
+
 // src/providers/config.ts
 var DEFAULT_MODELS = {
   openai: "gpt-5-mini",
@@ -926,6 +1196,12 @@ function toTaskDrafts(value) {
   }
   return out;
 }
+function refinementSystemPrompt(mode) {
+  if (mode === "idea") {
+    return "Return ONLY JSON object with keys summary and proposals. proposals must be an array of task proposals with action(create), title, type, priority, track, acceptance, tests_required, body.";
+  }
+  return "Return ONLY JSON object with keys summary and proposals. proposals must be an array with one update proposal containing action(update), target_id, title, type, status, track, priority, depends_on, acceptance, tests_required, authority_refs, derived_refs, body.";
+}
 function asAgentResponse(text, tokens) {
   return {
     summary: text.trim(),
@@ -967,19 +1243,44 @@ function create_provider_idea_decomposer(config) {
     }
   };
 }
+function create_provider_refinement_client(config) {
+  const provider = create_provider(config);
+  return {
+    async refineIdea(prompt, input) {
+      const result = await provider.complete({
+        system: refinementSystemPrompt("idea"),
+        prompt
+      });
+      return parseRefinementDraftResponse(result.text, "idea", input.idea_id, input.title);
+    },
+    async refineTask(prompt, input) {
+      const result = await provider.complete({
+        system: refinementSystemPrompt("task"),
+        prompt
+      });
+      return parseRefinementDraftResponse(result.text, "task", input.task.id, input.task.title);
+    }
+  };
+}
 export {
+  buildIdeaRefinementPrompt,
+  buildTaskRefinementPrompt,
   build_contract,
   build_decomposition_prompt,
   constraint_violation_reasons,
   create_provider,
   create_provider_agent_client,
   create_provider_idea_decomposer,
+  create_provider_refinement_client,
   create_run,
   decompose_idea_to_tasks,
   enforce_constraints,
   execute_task,
   finalize_run,
   log_step,
+  parseRefinementDraftResponse,
+  refine_idea_to_draft,
+  refine_task_to_draft,
   resolve_provider_config,
   select_agent,
   validate_command,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitsy/coop-ai",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.ts",
@@ -17,7 +17,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@kitsy/coop-core": "1.0.0"
+    "@kitsy/coop-core": "2.1.0"
   },
   "devDependencies": {
     "@types/node": "^24.12.0",