@kitsy/coop 2.2.4 → 2.2.5

package/dist/index.js

@@ -1888,6 +1888,8 @@ function promoteTaskForContext(task, context) {
   const next = {
     ...task,
     updated: todayIsoDate(),
+    promoted_at: (/* @__PURE__ */ new Date()).toISOString(),
+    promoted_track: context.track?.trim() || null,
     fix_versions: [...task.fix_versions ?? []],
     delivery_tracks: [...task.delivery_tracks ?? []],
     priority_context: { ...task.priority_context ?? {} }
@@ -2672,6 +2674,12 @@ function asUniqueStrings(value) {
   );
   return entries.length > 0 ? entries : void 0;
 }
+function formatIgnoredFieldWarning(source, context, keys) {
+  if (keys.length === 0) {
+    return "";
+  }
+  return `${source}: ignored unknown ${context} field(s): ${keys.sort((a, b) => a.localeCompare(b)).join(", ")}`;
+}
 function parseIdeaDraftObject(record, source) {
   const title = typeof record.title === "string" ? record.title.trim() : "";
   if (!title) {
@@ -2681,25 +2689,34 @@ function parseIdeaDraftObject(record, source) {
   if (status && !Object.values(IdeaStatus).includes(status)) {
     throw new Error(`${source}: invalid idea status '${status}'.`);
   }
+  const allowedKeys = /* @__PURE__ */ new Set(["id", "title", "author", "source", "status", "tags", "aliases", "linked_tasks", "body"]);
+  const ignoredKeys = Object.keys(record).filter((key) => !allowedKeys.has(key));
   return {
-    id: typeof record.id === "string" && record.id.trim() ? record.id.trim().toUpperCase() : void 0,
-    title,
-    author: typeof record.author === "string" && record.author.trim() ? record.author.trim() : void 0,
-    source: typeof record.source === "string" && record.source.trim() ? record.source.trim() : void 0,
-    status: status ? status : void 0,
-    tags: asUniqueStrings(record.tags),
-    aliases: asUniqueStrings(record.aliases),
-    linked_tasks: asUniqueStrings(record.linked_tasks),
-    body: typeof record.body === "string" ? record.body : void 0
+    value: {
+      id: typeof record.id === "string" && record.id.trim() ? record.id.trim().toUpperCase() : void 0,
+      title,
+      author: typeof record.author === "string" && record.author.trim() ? record.author.trim() : void 0,
+      source: typeof record.source === "string" && record.source.trim() ? record.source.trim() : void 0,
+      status: status ? status : void 0,
+      tags: asUniqueStrings(record.tags),
+      aliases: asUniqueStrings(record.aliases),
+      linked_tasks: asUniqueStrings(record.linked_tasks),
+      body: typeof record.body === "string" ? record.body : void 0
+    },
+    warnings: ignoredKeys.length > 0 ? [formatIgnoredFieldWarning(source, "idea draft", ignoredKeys)] : []
   };
 }
-function parseIdeaDraftInput(content, source) {
+function parseIdeaDraftInputWithWarnings(content, source) {
   const trimmed = content.trimStart();
   if (trimmed.startsWith("---")) {
     const { frontmatter, body } = parseFrontmatterContent(content, source);
+    const parsed = parseIdeaDraftObject(frontmatter, source);
     return {
-      ...parseIdeaDraftObject(frontmatter, source),
-      body: body || (typeof frontmatter.body === "string" ? frontmatter.body : void 0)
+      value: {
+        ...parsed.value,
+        body: body || (typeof frontmatter.body === "string" ? frontmatter.body : void 0)
+      },
+      warnings: parsed.warnings
     };
   }
   return parseIdeaDraftObject(parseYamlContent(content, source), source);
@@ -2770,6 +2787,12 @@ function nonEmptyStrings(value) {
   const entries = value.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
   return entries.length > 0 ? entries : void 0;
 }
+function formatIgnoredFieldWarning2(source, context, keys) {
+  if (keys.length === 0) {
+    return "";
+  }
+  return `${source}: ignored unknown ${context} field(s): ${keys.sort((a, b) => a.localeCompare(b)).join(", ")}`;
+}
 function refinementDir(projectDir) {
   const dir = path7.join(projectDir, "tmp", "refinements");
   fs6.mkdirSync(dir, { recursive: true });
@@ -2826,7 +2849,7 @@ function printDraftSummary(root, draft, filePath) {
   }
   console.log(`[COOP] apply with: coop apply draft --from-file ${path7.relative(root, filePath)}`);
 }
-function parseRefinementDraftInput(content, source) {
+function parseRefinementDraftInputWithWarnings(content, source) {
   const parsed = parseYamlContent2(content, source);
   if (parsed.kind !== "refinement_draft" || parsed.version !== 1) {
     throw new Error(`${source}: not a supported COOP refinement draft.`);
@@ -2838,7 +2861,34 @@ function parseRefinementDraftInput(content, source) {
   const sourceId = typeof sourceRecord.id === "string" ? sourceRecord.id : "";
   const sourceTitle = typeof sourceRecord.title === "string" ? sourceRecord.title : sourceId;
   const proposalsRaw = Array.isArray(parsed.proposals) ? parsed.proposals : [];
-  const proposals = proposalsRaw.map((entry) => {
+  const warnings = [];
+  const draftAllowedKeys = /* @__PURE__ */ new Set(["kind", "version", "mode", "source", "summary", "generated_at", "proposals"]);
+  const ignoredDraftKeys = Object.keys(parsed).filter((key) => !draftAllowedKeys.has(key));
+  if (ignoredDraftKeys.length > 0) {
+    warnings.push(formatIgnoredFieldWarning2(source, "refinement draft", ignoredDraftKeys));
+  }
+  const sourceAllowedKeys = /* @__PURE__ */ new Set(["id", "title"]);
+  const ignoredSourceKeys = Object.keys(sourceRecord).filter((key) => !sourceAllowedKeys.has(key));
+  if (ignoredSourceKeys.length > 0) {
+    warnings.push(formatIgnoredFieldWarning2(source, "refinement draft source", ignoredSourceKeys));
+  }
+  const proposalAllowedKeys = /* @__PURE__ */ new Set([
+    "action",
+    "id",
+    "target_id",
+    "title",
+    "type",
+    "status",
+    "track",
+    "priority",
+    "depends_on",
+    "acceptance",
+    "tests_required",
+    "authority_refs",
+    "derived_refs",
+    "body"
+  ]);
+  const proposals = proposalsRaw.map((entry, index) => {
     if (!isObject2(entry)) {
       throw new Error(`${source}: refinement draft proposal must be an object.`);
     }
@@ -2850,6 +2900,10 @@ function parseRefinementDraftInput(content, source) {
     if (!title) {
       throw new Error(`${source}: refinement draft proposal title is required.`);
     }
+    const ignoredProposalKeys = Object.keys(entry).filter((key) => !proposalAllowedKeys.has(key));
+    if (ignoredProposalKeys.length > 0) {
+      warnings.push(formatIgnoredFieldWarning2(source, `refinement draft proposal ${index + 1}`, ignoredProposalKeys));
+    }
     return {
       action,
       id: typeof entry.id === "string" ? entry.id.trim() || void 0 : void 0,
@@ -2871,17 +2925,20 @@ function parseRefinementDraftInput(content, source) {
     throw new Error(`${source}: refinement draft has no proposals.`);
   }
   return {
-    kind: "refinement_draft",
-    version: 1,
-    mode: parsed.mode,
-    source: {
-      entity_type: parsed.mode,
-      id: sourceId,
-      title: sourceTitle
+    value: {
+      kind: "refinement_draft",
+      version: 1,
+      mode: parsed.mode,
+      source: {
+        entity_type: parsed.mode,
+        id: sourceId,
+        title: sourceTitle
+      },
+      summary: typeof parsed.summary === "string" && parsed.summary.trim() ? parsed.summary.trim() : `Refinement draft for ${sourceId}`,
+      generated_at: typeof parsed.generated_at === "string" && parsed.generated_at.trim() ? parsed.generated_at.trim() : (/* @__PURE__ */ new Date()).toISOString(),
+      proposals
     },
-    summary: typeof parsed.summary === "string" && parsed.summary.trim() ? parsed.summary.trim() : `Refinement draft for ${sourceId}`,
-    generated_at: typeof parsed.generated_at === "string" && parsed.generated_at.trim() ? parsed.generated_at.trim() : (/* @__PURE__ */ new Date()).toISOString(),
-    proposals
+    warnings
   };
 }
 function taskFromProposal(proposal, fallbackDate) {
@@ -2988,50 +3045,78 @@ function parseTaskDraftObject(record, source) {
   const 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;
   const priority = record.priority === "p0" || record.priority === "p1" || record.priority === "p2" || record.priority === "p3" ? record.priority : void 0;
   const origin = isObject2(record.origin) ? record.origin : {};
+  const taskAllowedKeys = /* @__PURE__ */ new Set([
+    "id",
+    "title",
+    "type",
+    "status",
+    "track",
+    "priority",
+    "depends_on",
+    "acceptance",
+    "tests_required",
+    "authority_refs",
+    "derived_refs",
+    "origin",
+    "body"
+  ]);
+  const originAllowedKeys = /* @__PURE__ */ new Set(["authority_refs", "derived_refs"]);
+  const ignoredTaskKeys = Object.keys(record).filter((key) => !taskAllowedKeys.has(key));
+  const ignoredOriginKeys = Object.keys(origin).filter((key) => !originAllowedKeys.has(key));
+  const warnings = [];
+  if (ignoredTaskKeys.length > 0) {
+    warnings.push(formatIgnoredFieldWarning2(source, "task draft", ignoredTaskKeys));
+  }
+  if (ignoredOriginKeys.length > 0) {
+    warnings.push(formatIgnoredFieldWarning2(source, "task draft origin", ignoredOriginKeys));
+  }
   return {
-    kind: "refinement_draft",
-    version: 1,
-    mode: "task",
-    source: {
-      entity_type: "task",
-      id: id ?? "draft-task",
-      title
+    value: {
+      kind: "refinement_draft",
+      version: 1,
+      mode: "task",
+      source: {
+        entity_type: "task",
+        id: id ?? "draft-task",
+        title
+      },
+      summary: `Imported task draft for ${title}`,
+      generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      proposals: [
+        {
+          action: "create",
+          id,
+          title,
+          type,
+          status,
+          track: typeof record.track === "string" ? record.track.trim() || void 0 : void 0,
+          priority,
+          depends_on: nonEmptyStrings(record.depends_on),
+          acceptance: nonEmptyStrings(record.acceptance),
+          tests_required: nonEmptyStrings(record.tests_required),
+          authority_refs: nonEmptyStrings(record.authority_refs) ?? nonEmptyStrings(origin.authority_refs),
+          derived_refs: nonEmptyStrings(record.derived_refs) ?? nonEmptyStrings(origin.derived_refs),
+          body: typeof record.body === "string" ? record.body : void 0
+        }
+      ]
     },
-    summary: `Imported task draft for ${title}`,
-    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
-    proposals: [
-      {
-        action: "create",
-        id,
-        title,
-        type,
-        status,
-        track: typeof record.track === "string" ? record.track.trim() || void 0 : void 0,
-        priority,
-        depends_on: nonEmptyStrings(record.depends_on),
-        acceptance: nonEmptyStrings(record.acceptance),
-        tests_required: nonEmptyStrings(record.tests_required),
-        authority_refs: nonEmptyStrings(record.authority_refs) ?? nonEmptyStrings(origin.authority_refs),
-        derived_refs: nonEmptyStrings(record.derived_refs) ?? nonEmptyStrings(origin.derived_refs),
-        body: typeof record.body === "string" ? record.body : void 0
-      }
-    ]
+    warnings
   };
 }
-function parseTaskDraftOrRefinement(content, source) {
+function parseTaskDraftOrRefinementWithWarnings(content, source) {
   const trimmed = content.trimStart();
   if (trimmed.startsWith("---")) {
     const { frontmatter, body } = parseFrontmatterContent2(content, source);
-    const draft = parseTaskDraftObject(frontmatter, source);
-    draft.proposals[0] = {
-      ...draft.proposals[0],
-      body: body || draft.proposals[0]?.body
+    const parsed2 = parseTaskDraftObject(frontmatter, source);
+    parsed2.value.proposals[0] = {
+      ...parsed2.value.proposals[0],
+      body: body || parsed2.value.proposals[0]?.body
     };
-    return draft;
+    return parsed2;
   }
   const parsed = parseYamlContent2(content, source);
   if (parsed.kind === "refinement_draft") {
-    return parseRefinementDraftInput(content, source);
+    return parseRefinementDraftInputWithWarnings(content, source);
   }
   return parseTaskDraftObject(parsed, source);
 }
@@ -3047,8 +3132,12 @@ function parseCsv(value) {
   if (!value) return [];
   return value.split(",").map((entry) => entry.trim()).filter(Boolean);
 }
-function collectMultiValue(value, previous = []) {
-  return [...previous, ...parseCsv(value)];
+function collectRepeatedValue(value, previous = []) {
+  const next = value.trim();
+  if (!next) {
+    return previous;
+  }
+  return [...previous, next];
 }
 function toNumber(value, field) {
   if (value == null || value.trim().length === 0) return void 0;
@@ -3066,6 +3155,11 @@ function plusDaysIso(days) {
 function unique2(values) {
   return Array.from(new Set(values));
 }
+function printDraftWarnings(warnings) {
+  for (const warning of warnings) {
+    console.warn(`[COOP][warn] ${warning}`);
+  }
+}
 function assertNoCaseInsensitiveNameConflict(kind, entries, candidateId, candidateName) {
   const normalizedName = candidateName.trim().toLowerCase();
   if (!normalizedName) {
@@ -3153,7 +3247,7 @@ function makeTaskDraft(input2) {
 }
 function registerCreateCommand(program) {
   const create = program.command("create").description("Create COOP entities");
-  create.command("task").description("Create a task").allowUnknownOption().allowExcessArguments().argument("[title]", "Task title").option("--id <id>", "Task id").option("--from <idea>", "Create task(s) from an idea id/alias").option("--ai", "Use AI-assisted decomposition for --from").option("--title <title>", "Task title").option("--type <type>", `Task type (${Object.values(TaskType2).join(", ")})`).option("--status <status>", `Task status (${Object.values(TaskStatus3).join(", ")})`).option("--track <track>", "Home/origin track id").option("--delivery <delivery>", "Primary delivery id").option("--priority <priority>", "Task priority").option("--body <body>", "Markdown body").option("--acceptance <items>", "Comma-separated acceptance criteria", collectMultiValue, []).option("--tests-required <items>", "Comma-separated required tests", collectMultiValue, []).option("--authority-ref <ref>", "Authority document reference", collectMultiValue, []).option("--derived-ref <ref>", "Derived planning document reference", collectMultiValue, []).option("--from-file <path>", "Create task(s) from task draft/refinement draft file").option("--stdin", "Read task draft/refinement draft from stdin").option("--interactive", "Prompt for optional fields").action(async (titleArg, options) => {
+  create.command("task").description("Create a task").allowUnknownOption().allowExcessArguments().argument("[title]", "Task title").option("--id <id>", "Task id").option("--from <idea>", "Create task(s) from an idea id/alias").option("--ai", "Use AI-assisted decomposition for --from").option("--title <title>", "Task title").option("--type <type>", `Task type (${Object.values(TaskType2).join(", ")})`).option("--status <status>", `Task status (${Object.values(TaskStatus3).join(", ")})`).option("--track <track>", "Home/origin track id").option("--delivery <delivery>", "Primary delivery id").option("--priority <priority>", "Task priority").option("--body <body>", "Markdown body").option("--acceptance <text>", "Acceptance criterion; repeat the flag to add multiple entries", collectRepeatedValue, []).option("--tests-required <text>", "Required test; repeat the flag to add multiple entries", collectRepeatedValue, []).option("--authority-ref <ref>", "Authority document reference; repeat the flag to add multiple entries", collectRepeatedValue, []).option("--derived-ref <ref>", "Derived planning document reference; repeat the flag to add multiple entries", collectRepeatedValue, []).option("--from-file <path>", "Create task(s) from task draft/refinement draft file").option("--stdin", "Read task draft/refinement draft from stdin").option("--interactive", "Prompt for optional fields").action(async (titleArg, options) => {
     const root = resolveRepoRoot();
     const coop = ensureCoopInitialized(root);
     const interactive = Boolean(options.interactive);
@@ -3189,8 +3283,10 @@ function registerCreateCommand(program) {
         fromFile: options.fromFile,
         stdin: options.stdin
       });
+      const parsedDraftResult = parseTaskDraftOrRefinementWithWarnings(draftInput.content, draftInput.source);
+      printDraftWarnings(parsedDraftResult.warnings);
       const parsedDraft = ensureValidCreateOnlyDraft(
-        assignCreateProposalIds(root, parseTaskDraftOrRefinement(draftInput.content, draftInput.source)),
+        assignCreateProposalIds(root, parsedDraftResult.value),
         draftInput.source
       );
       const written = applyRefinementDraft(root, coop, parsedDraft);
@@ -3370,7 +3466,9 @@ function registerCreateCommand(program) {
         fromFile: options.fromFile,
         stdin: options.stdin
       });
-      const written = writeIdeaFromDraft(root, coop, parseIdeaDraftInput(draftInput.content, draftInput.source));
+      const parsedIdeaDraft = parseIdeaDraftInputWithWarnings(draftInput.content, draftInput.source);
+      printDraftWarnings(parsedIdeaDraft.warnings);
+      const written = writeIdeaFromDraft(root, coop, parsedIdeaDraft.value);
       console.log(`[COOP] created 1 idea file from ${draftInput.source}`);
       console.log(`Created idea: ${path8.relative(root, written)}`);
       return;
@@ -3971,19 +4069,19 @@ var catalog = {
       description: "Create ideas, tasks, tracks, and deliveries.",
       commands: [
         { usage: 'coop create idea "Subscription page"', purpose: "Create an idea with a positional title." },
-        { usage: "coop create idea --from-file idea-draft.yml", purpose: "Ingest a structured idea draft file." },
-        { usage: "cat idea.md | coop create idea --stdin", purpose: "Ingest an idea draft from stdin." },
+        { usage: "coop create idea --from-file idea-draft.yml", purpose: "Ingest a structured idea draft file; COOP keeps only recognized fields, synthesizes canonical metadata, and warns on ignored fields." },
+        { usage: "cat idea.md | coop create idea --stdin", purpose: "Ingest an idea draft from stdin with the same schema-filtered behavior." },
         { usage: 'coop create task "Implement webhook pipeline"', purpose: "Create a task with defaults." },
         { usage: 'coop create task "UX: Auth user journey" --id UX-AUTH-1', purpose: "Create a task with an explicit primary ID." },
         { usage: 'coop create task "UX: Auth user journey" --proj UX --feat AUTH', purpose: "Create a task using configured naming tokens." },
         { usage: 'coop create task --title "Lock auth contract" --track MVP --delivery MVP', purpose: "Create a task directly inside a track and delivery scope." },
         { usage: "coop create track MVP", purpose: "Create a named track with slug-style default ID." },
         {
-          usage: 'coop create task --title "Lock auth contract" --acceptance "Contract approved,Client mapping documented" --tests-required "Contract fixture test" --authority-ref docs/webapp-mvp-plan.md#auth',
-          purpose: "Create a planning-grade task with acceptance, tests, and origin refs."
+          usage: 'coop create task --title "Lock auth contract" --acceptance "Contract approved, client mapping documented" --acceptance "Rollback path documented" --tests-required "Contract fixture test" --authority-ref docs/webapp-mvp-plan.md#auth',
+          purpose: "Create a planning-grade task with repeatable free-text acceptance/tests fields and origin refs."
         },
-        { usage: "coop create task --from-file task-draft.yml", purpose: "Ingest a structured task draft file." },
-        { usage: "cat task.md | coop create task --stdin", purpose: "Ingest a task draft from stdin." },
+        { usage: "coop create task --from-file task-draft.yml", purpose: "Ingest a structured task draft file; COOP keeps only recognized fields, synthesizes canonical metadata, and warns on ignored fields." },
+        { usage: "cat task.md | coop create task --stdin", purpose: "Ingest a task draft from stdin with the same schema-filtered behavior." },
         { usage: "coop create delivery --name MVP --scope PM-100,PM-101", purpose: "Create a delivery from task scope." }
       ]
     },
@@ -3995,7 +4093,7 @@ var catalog = {
         { usage: "coop refine idea IDEA-101 --apply", purpose: "Refine an idea and apply the resulting draft." },
         { usage: "coop refine task PM-101", purpose: "Enrich a task with planning context and execution detail." },
         { usage: "coop refine task PM-101 --input-file docs/plan.md", purpose: "Use an additional planning brief during refinement." },
-        { usage: "cat refinement.yml | coop apply draft --stdin", purpose: "Apply a refinement draft streamed from another process." }
+        { usage: "cat refinement.yml | coop apply draft --stdin", purpose: "Apply a refinement draft streamed from another process; unknown draft fields are ignored with warnings." }
       ]
     },
     {
@@ -4007,7 +4105,7 @@ var catalog = {
         { usage: "coop pick task PM-101 --promote --claim --actor dev1 --user lead-user", purpose: "Select a specific task, optionally promote it in the current context, assign it, and move it to in_progress." },
         { usage: "coop pick task --delivery MVP --claim --actor dev1 --user lead-user", purpose: "Select the top ready task, optionally assign it, and move it to in_progress." },
         { usage: "coop start task PM-101 --promote --claim --actor dev1 --user lead-user", purpose: "Start a specific task or the top ready task if no id is provided." },
-        { usage: "coop promote task PM-101", purpose: "Promote a task using the current working track/version context." },
+        { usage: "coop promote task PM-101", purpose: "Promote a task using the current working track/version context; the promoted task moves to the top of that selection lens." },
         { usage: "coop review task PM-101", purpose: "Move an in-progress task into in_review using a DX-friendly verb." },
         { usage: "coop complete task PM-101", purpose: "Move a task in review into done using a DX-friendly verb." },
         { usage: "coop block task PM-101", purpose: "Mark a task as blocked." },
@@ -4036,6 +4134,11 @@ var catalog = {
         { usage: "coop update PM-101 --track MVP --delivery MVP", purpose: "Update a task's home track or primary delivery without editing `.coop` files directly." },
         { usage: "coop update PM-101 --add-delivery-track MVP --priority-in MVP:p0", purpose: "Add a contributing track lens and scoped priority override." },
         { usage: "coop update PM-101 --priority p1 --add-fix-version v2", purpose: "Update task metadata without editing `.coop` files directly." },
+        { usage: 'coop update PM-101 --acceptance-set "Contract approved, client mapping documented" --acceptance-set "Rollback path documented"', purpose: "Replace the full acceptance list with repeatable free-text entries; useful when an older task was created with the wrong parsing." },
+        { usage: 'coop update PM-101 --tests-set "Contract fixture test" --tests-set "Integration smoke"', purpose: "Replace the full tests_required list with repeatable entries." },
+        { usage: "coop update PM-101 --authority-ref-set docs/spec.md#auth --derived-ref-set docs/plan.md#scope", purpose: "Replace the full origin reference lists without editing task files directly." },
+        { usage: "coop update PM-101 --deps-set PM-201 --deps-set PM-202 --delivery-tracks-set MVP", purpose: "Replace identifier-based list fields such as depends_on and delivery_tracks." },
+        { usage: "coop update IDEA-101 --linked-tasks-set PM-101 --linked-tasks-set PM-102", purpose: "Replace the full linked_tasks list on an idea." },
         { usage: 'coop comment PM-101 --message "Needs API review"', purpose: "Append a comment to a task." },
         { usage: 'coop log-time PM-101 --hours 2 --kind worked --note "pairing"', purpose: "Append a planned or worked time log to a task." },
         { usage: "coop alias remove PM-101 PAY.UPI", purpose: "Remove an alias from a task or idea." },
@@ -4081,7 +4184,10 @@ var catalog = {
   execution_model: [
     "Agents or services may send drafts through files or stdin, but COOP owns canonical writes.",
     "Use `coop create ... --from-file|--stdin` and `coop apply draft` instead of editing `.coop` task or idea files directly.",
+    "Draft files are input bundles, not raw frontmatter passthrough. COOP keeps only recognized fields, fills canonical metadata itself, and warns when it ignores unknown fields.",
+    "For task creation, repeat `--acceptance`, `--tests-required`, `--authority-ref`, and `--derived-ref` to append multiple entries. Commas inside one value are preserved.",
     "Use `coop update`, `coop comment`, and `coop log-time` for task mutations instead of manually editing task files.",
+    "When a mutable list field needs correction, prefer the `--...-set` variants on `coop update` over manual file edits. This applies to acceptance, tests_required, authority_refs, derived_refs, depends_on, delivery_tracks, tags, fix_versions, released_in, and idea linked_tasks.",
     "Use `coop log --last --verbose` when command execution fails and the concise error points to a stack trace.",
     "If a workflow depends on stable human-readable IDs, inspect `coop naming` or `coop config id.naming` before creating items."
   ],
@@ -7023,7 +7129,11 @@ function registerRefineCommand(program) {
     const root = resolveRepoRoot();
     const projectDir = ensureCoopInitialized(root);
     const draftInput = await readDraftContent(root, options);
-    const draft = parseRefinementDraftInput(draftInput.content, draftInput.source);
+    const parsedDraft = parseRefinementDraftInputWithWarnings(draftInput.content, draftInput.source);
+    for (const warning of parsedDraft.warnings) {
+      console.warn(`[COOP][warn] ${warning}`);
+    }
+    const draft = parsedDraft.value;
     const written = applyRefinementDraft(root, projectDir, draft);
     console.log(`[COOP] applied draft from ${draftInput.source}: ${written.length} task file(s) updated`);
     for (const filePath of written) {
@@ -8133,6 +8243,13 @@ function addValues(source, values) {
   const next = unique3([...source ?? [], ...values ?? []]);
   return next.length > 0 ? next : void 0;
 }
+function setValues(values) {
+  if (!values || values.length === 0) {
+    return void 0;
+  }
+  const next = unique3(values);
+  return next.length > 0 ? next : void 0;
+}
 function loadBody(options) {
   if (options.bodyFile) {
     return fs20.readFileSync(options.bodyFile, "utf8");
@@ -8186,6 +8303,29 @@ function normalizeTaskPriority(priority) {
 function renderTaskPreview(task, body) {
   return stringifyFrontmatter5(task, body);
 }
+function normalizeOrigin(task, authorityRefs, derivedRefs) {
+  const nextOrigin = {
+    ...task.origin ?? {},
+    authority_refs: authorityRefs,
+    derived_refs: derivedRefs
+  };
+  const hasAuthority = Array.isArray(nextOrigin.authority_refs) && nextOrigin.authority_refs.length > 0;
+  const hasDerived = Array.isArray(nextOrigin.derived_refs) && nextOrigin.derived_refs.length > 0;
+  const hasPromoted = Array.isArray(nextOrigin.promoted_from) && nextOrigin.promoted_from.length > 0;
+  if (!hasAuthority) {
+    delete nextOrigin.authority_refs;
+  }
+  if (!hasDerived) {
+    delete nextOrigin.derived_refs;
+  }
+  if (!hasPromoted) {
+    delete nextOrigin.promoted_from;
+  }
+  return {
+    ...task,
+    origin: hasAuthority || hasDerived || hasPromoted ? nextOrigin : void 0
+  };
+}
 function updateTask(id, options) {
   const root = resolveRepoRoot();
   const { filePath, parsed } = loadTaskEntry(root, id);
@@ -8201,16 +8341,19 @@ function updateTask(id, options) {
   if (options.delivery !== void 0) next.delivery = options.delivery.trim() || null;
   if (options.storyPoints !== void 0) next.story_points = Number(options.storyPoints);
   if (options.plannedHours !== void 0) next = setTaskPlannedHours(next, Number(options.plannedHours));
+  const nextAuthorityRefs = options.authorityRefSet && options.authorityRefSet.length > 0 ? setValues(options.authorityRefSet) : addValues(removeValues(next.origin?.authority_refs, options.authorityRefRemove), options.authorityRefAdd);
+  const nextDerivedRefs = options.derivedRefSet && options.derivedRefSet.length > 0 ? setValues(options.derivedRefSet) : addValues(removeValues(next.origin?.derived_refs, options.derivedRefRemove), options.derivedRefAdd);
   next = {
     ...next,
-    delivery_tracks: addValues(removeValues(next.delivery_tracks, options.removeDeliveryTrack), options.addDeliveryTrack),
-    depends_on: addValues(removeValues(next.depends_on, options.removeDep), options.addDep),
-    tags: addValues(removeValues(next.tags, options.removeTag), options.addTag),
-    fix_versions: addValues(removeValues(next.fix_versions, options.removeFixVersion), options.addFixVersion),
-    released_in: addValues(removeValues(next.released_in, options.removeReleasedIn), options.addReleasedIn),
-    acceptance: addValues(removeValues(next.acceptance, options.acceptanceRemove), options.acceptanceAdd),
-    tests_required: addValues(removeValues(next.tests_required, options.testsRemove), options.testsAdd)
+    delivery_tracks: options.deliveryTracksSet && options.deliveryTracksSet.length > 0 ? setValues(options.deliveryTracksSet) : addValues(removeValues(next.delivery_tracks, options.removeDeliveryTrack), options.addDeliveryTrack),
+    depends_on: options.depsSet && options.depsSet.length > 0 ? setValues(options.depsSet) : addValues(removeValues(next.depends_on, options.removeDep), options.addDep),
+    tags: options.tagsSet && options.tagsSet.length > 0 ? setValues(options.tagsSet) : addValues(removeValues(next.tags, options.removeTag), options.addTag),
+    fix_versions: options.fixVersionsSet && options.fixVersionsSet.length > 0 ? setValues(options.fixVersionsSet) : addValues(removeValues(next.fix_versions, options.removeFixVersion), options.addFixVersion),
+    released_in: options.releasedInSet && options.releasedInSet.length > 0 ? setValues(options.releasedInSet) : addValues(removeValues(next.released_in, options.removeReleasedIn), options.addReleasedIn),
+    acceptance: options.acceptanceSet && options.acceptanceSet.length > 0 ? setValues(options.acceptanceSet) : addValues(removeValues(next.acceptance, options.acceptanceRemove), options.acceptanceAdd),
+    tests_required: options.testsSet && options.testsSet.length > 0 ? setValues(options.testsSet) : addValues(removeValues(next.tests_required, options.testsRemove), options.testsAdd)
   };
+  next = normalizeOrigin(next, nextAuthorityRefs, nextDerivedRefs);
   next = clearTrackPriorityOverrides(applyTrackPriorityOverrides(next, options.priorityIn), options.clearPriorityIn);
   next = validateTaskForWrite(root, next, filePath);
   const nextBody = loadBody(options) ?? parsed.body;
@@ -8232,8 +8375,8 @@ function updateIdea(id, options) {
     ...parsed.idea,
     title: options.title?.trim() || parsed.idea.title,
     status: nextStatus || parsed.idea.status,
-    tags: addValues(removeValues(parsed.idea.tags, options.removeTag), options.addTag) ?? [],
-    linked_tasks: addValues(removeValues(parsed.idea.linked_tasks, options.removeLinkedTask), options.addLinkedTask) ?? []
+    tags: (options.tagsSet && options.tagsSet.length > 0 ? setValues(options.tagsSet) : addValues(removeValues(parsed.idea.tags, options.removeTag), options.addTag)) ?? [],
+    linked_tasks: (options.linkedTasksSet && options.linkedTasksSet.length > 0 ? setValues(options.linkedTasksSet) : addValues(removeValues(parsed.idea.linked_tasks, options.removeLinkedTask), options.addLinkedTask)) ?? []
   };
   const nextBody = loadBody(options) ?? parsed.body;
   if (options.dryRun) {
@@ -8244,7 +8387,7 @@ function updateIdea(id, options) {
   console.log(`Updated ${next.id}`);
 }
 function registerUpdateCommand(program) {
-  program.command("update").description("Update an existing COOP task or idea").argument("<id-or-type>", "Task or idea id/alias, or an explicit entity type").argument("[id]", "Entity id when an explicit type is provided").option("--title <title>").option("--priority <priority>").option("--status <status>").option("--assign <user>").option("--track <id>", "Set the task home/origin track").option("--delivery <id>", "Set the task primary delivery id").option("--story-points <n>").option("--planned-hours <n>").option("--add-delivery-track <id>", "", collect, []).option("--remove-delivery-track <id>", "", collect, []).option("--priority-in <track:priority>", "", collect, []).option("--clear-priority-in <track>", "", collect, []).option("--add-dep <id>", "", collect, []).option("--remove-dep <id>", "", collect, []).option("--add-tag <tag>", "", collect, []).option("--remove-tag <tag>", "", collect, []).option("--add-fix-version <v>", "", collect, []).option("--remove-fix-version <v>", "", collect, []).option("--add-released-in <v>", "", collect, []).option("--remove-released-in <v>", "", collect, []).option("--acceptance-add <text>", "", collect, []).option("--acceptance-remove <text>", "", collect, []).option("--tests-add <text>", "", collect, []).option("--tests-remove <text>", "", collect, []).option("--add-linked-task <id>", "", collect, []).option("--remove-linked-task <id>", "", collect, []).option("--body-file <path>").option("--body-stdin").option("--dry-run").action((first, second, options) => {
+  program.command("update").description("Update an existing COOP task or idea").argument("<id-or-type>", "Task or idea id/alias, or an explicit entity type").argument("[id]", "Entity id when an explicit type is provided").option("--title <title>").option("--priority <priority>").option("--status <status>").option("--assign <user>").option("--track <id>", "Set the task home/origin track").option("--delivery <id>", "Set the task primary delivery id").option("--story-points <n>").option("--planned-hours <n>").option("--delivery-tracks-set <id>", "Replace the full delivery_tracks list", collect, []).option("--add-delivery-track <id>", "", collect, []).option("--remove-delivery-track <id>", "", collect, []).option("--priority-in <track:priority>", "", collect, []).option("--clear-priority-in <track>", "", collect, []).option("--deps-set <id>", "Replace the full depends_on list", collect, []).option("--add-dep <id>", "", collect, []).option("--remove-dep <id>", "", collect, []).option("--tags-set <tag>", "Replace the full tags list", collect, []).option("--add-tag <tag>", "", collect, []).option("--remove-tag <tag>", "", collect, []).option("--fix-versions-set <v>", "Replace the full fix_versions list", collect, []).option("--add-fix-version <v>", "", collect, []).option("--remove-fix-version <v>", "", collect, []).option("--released-in-set <v>", "Replace the full released_in list", collect, []).option("--add-released-in <v>", "", collect, []).option("--remove-released-in <v>", "", collect, []).option("--authority-ref-set <ref>", "Replace the full authority_refs list", collect, []).option("--authority-ref-add <ref>", "", collect, []).option("--authority-ref-remove <ref>", "", collect, []).option("--derived-ref-set <ref>", "Replace the full derived_refs list", collect, []).option("--derived-ref-add <ref>", "", collect, []).option("--derived-ref-remove <ref>", "", collect, []).option("--acceptance-set <text>", "Replace the full acceptance list; repeat the flag to set multiple entries", collect, []).option("--acceptance-add <text>", "", collect, []).option("--acceptance-remove <text>", "", collect, []).option("--tests-set <text>", "Replace the full tests_required list; repeat the flag to set multiple entries", collect, []).option("--tests-add <text>", "", collect, []).option("--tests-remove <text>", "", collect, []).option("--linked-tasks-set <id>", "Replace the full linked_tasks list on an idea", collect, []).option("--add-linked-task <id>", "", collect, []).option("--remove-linked-task <id>", "", collect, []).option("--body-file <path>").option("--body-stdin").option("--dry-run").action((first, second, options) => {
     let resolved = resolveOptionalEntityArg(first, second, ["task", "idea"], "task");
     if (!second && resolved.entity === "task") {
       try {
@@ -8799,10 +8942,14 @@ function renderBasicHelp() {
     "- `coop naming`: inspect per-entity ID rules and naming tokens",
     '- `coop naming preview "Title" --entity task`: preview the generated ID before creating an item; templates support `TITLE##` like `TITLE18`, `TITLE8`, or `TITLE08`',
     "- `coop naming reset task`: reset one entity's naming template to the default",
+    "- `coop create task --from-file draft.yml` / `coop create idea --stdin`: ingest structured drafts; COOP keeps only recognized fields, fills metadata, and warns on ignored fields",
     "- `coop next task` or `coop pick task`: choose work from COOP",
+    "- `coop promote <id>`: move a task to the top of the current working track/version selection lens",
     "- `coop show <id>`: inspect a task, idea, or delivery",
     "- `coop list tasks --track <id>`: browse scoped work",
     "- `coop update <id> --track <id> --delivery <id>`: update task metadata",
+    '- `coop update <id> --acceptance-set "..." --acceptance-set "..."`: replace the whole acceptance list cleanly when an old task was created with the wrong parsing',
+    "- `coop update <id> --tests-set ... --authority-ref-set ... --deps-set ...`: the same full-replace pattern works for other mutable list fields too",
     '- `coop comment <id> --message "..."`: append a task comment',
     "- `coop log-time <id> --hours 2 --kind worked`: append time spent",
     "- `coop alias remove <id> <alias>`: remove a shorthand alias from a task or idea",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kitsy/coop",
   "description": "COOP command-line interface.",
-  "version": "2.2.4",
+  "version": "2.2.5",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -39,9 +39,9 @@
     "chalk": "^5.6.2",
     "commander": "^14.0.0",
     "octokit": "^5.0.5",
-    "@kitsy/coop-ai": "2.2.4",
-    "@kitsy/coop-core": "2.2.4",
-    "@kitsy/coop-ui": "^2.2.4"
+    "@kitsy/coop-ai": "2.2.5",
+    "@kitsy/coop-core": "2.2.5",
+    "@kitsy/coop-ui": "^2.2.5"
   },
   "devDependencies": {
     "@types/node": "^24.12.0",