@konductro/cursor-plugin 1.1.0 → 1.3.0

package/README.md

@@ -59,8 +59,11 @@ Tools are called automatically by Cursor's agent based on your requests:
 | `get_ticket_context` | Load full context for a ticket |
 | `start_work` | Create branch and start a ticket |
 | `create_pr` | Create a pull request for a ticket |
+| `create_work_item` | Create a story, task or bug in the project this repo belongs to |
+| `update_work_item` | Change the title, description or acceptance criteria of a work item you own |
+| `delete_work_item` | Delete a task or bug that has not been started |
 | `list_tech_analysis_tasks` | List tech analysis assignments |
-| `get_task_context` | Load tech analysis context |
+| `get_task_context` | Load tech analysis context, plus the requester's message when a refresh was asked for |
 | `submit_tech_analysis` | Submit analysis document |
 | `list_decomposition_tasks` | List story decomposition assignments |
 | `get_decomposition_context` | Load story context |
@@ -74,6 +77,67 @@ Tools are called automatically by Cursor's agent based on your requests:
 | `profile_repository` | Submit repository profile |
 | `find_project_prototypes` | Find UX prototypes for a project |
 
+### Work items
+
+The project is resolved from the repository's git remote, so you are never asked for a
+project identifier.
+
+**Everything created lands in Draft** and still needs an SDM's approval before it can be
+worked on.
+
+**`update_work_item` can change three fields and no others.** Status, sprint, assignee and
+everything else are deliberately not on the schema — change those in Konductro. Sending
+`acceptanceCriteria` replaces the whole list rather than appending to it. The `changed`
+list it reports back is the fields that were written, not the ones that turned out to
+differ, so re-sending a value unchanged still shows up in it.
+
+**A task is created in the repository you are standing in.** Its parent story is the only
+thing you need to name. Set `repositoryId` yourself only for a task that will be built in a
+different repository on the same project.
+
+**Only a task may have a parent.** A story or a bug sent with a `parentKey` is refused and
+nothing is created, rather than being filed top-level as though it had worked. A bug is
+always standalone here — Konductro parents one to a story only when QA files it against a
+failed test criterion — so name the story in the description instead. A story is top-level
+by definition: the hierarchy is story → task, and work that belongs under a story is a task.
+
+**`create_work_item` returns the new item's id.** Use it for the follow-up call. Ticket
+keys are prefix plus number and the prefix is not returned, so a guessed key resolves to a
+different project's item of the same number instead of failing.
+
+#### Who can create and change stories
+
+Each project has a story access setting, which an SDM controls under Settings → General:
+
+| Setting | What a developer can do |
+|---|---|
+| **Planning roles only** | Cannot create or change stories. Filing bugs and editing tasks are unaffected. |
+| **Developers can, with review** | Changes apply straight away, then wait for an SDM to approve or reject. |
+| **Developers can, no review** | Creates and changes apply with nothing held for approval. |
+
+A new project starts on **planning roles only**.
+
+Under *with review*, a change to a story is applied and then held: the story will not move
+to Ready for QA until an SDM resolves it, even once every task is done. If it is rejected,
+the previous values are restored and you are notified.
+
+#### What a refusal means
+
+These are answers, not errors — none of them is worth retrying as-is.
+
+| You will see | What to do |
+|---|---|
+| The project's story access is set to planning roles only | A project setting. Ask an SDM to make the change, or to open story access for developers. |
+| You can only change work items assigned to you, that you are the developer on, or that you created | Ask whoever owns it, or ask an SDM. |
+| Stories cannot be deleted from the CLI | Deleting a story removes its tasks with it. Archive it in Konductro instead. |
+| QA filed this bug against a failed test criterion | It is QA's record of a failure, not yours to remove. |
+| Only a task can be created under a parent | Nothing was created. For a bug, re-run without `parentKey` and name the story in the description. For a story, you probably wanted `kind: "task"`. |
+| Work has already started on this item | It has a branch, or has moved past sprint planning. Only items still in draft, approved or in_sprint can be deleted. |
+| Your seat is a viewer seat | Read-only across the whole platform, not a project setting. Ask an admin for a contributor seat. |
+| Your role on this project is read-only | Ask an SDM for a writing role on the project. |
+| You are not a member of this project | Ask an SDM to add you to the project team. |
+| Konductro is not configured | A setup problem rather than a permissions one — re-run `konductro-cursor-setup` with your URL and token. |
+
 ## Updating Your Token
 
 Run the setup command again with the new token:

package/bin/setup.js

@@ -136,6 +136,7 @@ function main() {
   console.log('  prototype            — build a UX prototype');
   console.log('  find-prototype       — find and download prototypes');
   console.log('  bug-enrich           — enrich a bug report');
+  console.log('  demand-analysis      — size a demand against the real code');
   console.log('');
   console.log('Reload Cursor to activate (Cmd+Shift+P → "Developer: Reload Window").');
   console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konductro/cursor-plugin",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Cursor IDE plugin for the Konductro platform: technical analysis, delivery tasks, repository profiling, and prototype workflows.",
   "license": "UNLICENSED",
   "type": "module",

package/servers/konductro-api.js

@@ -32,6 +32,24 @@ function loadFileConfig() {
 const fileConfig = loadFileConfig();
 const KONDUCTRO_URL = (process.env.KONDUCTRO_URL || fileConfig.url || fileConfig.konductroUrl || '').replace(/\/$/, '');
 const CLI_TOKEN = process.env.KONDUCTRO_CLI_TOKEN || fileConfig.token || fileConfig.cliToken || '';
+
+/*
+ * What this plugin tells the server it is, on every request.
+ *
+ * READ FROM package.json, never a constant. The server's refusal of an outdated plugin is
+ * based on this string, so a hand-maintained copy that drifts from the published version
+ * is worse than no header at all: it would be believed.
+ *
+ * `readFileSync` rather than a JSON import assertion, whose syntax differs between Node 18
+ * and 20 and would break for whichever developers are on the other one.
+ *
+ * The shape is `<plugin>/<version>` and is identical across all four plugins, so the
+ * server parses one format rather than four.
+ */
+const PLUGIN_VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
+const PLUGIN_ID = `cursor/${PLUGIN_VERSION}`;
 const NOT_CONFIGURED_MESSAGE =
   'Konductro is not configured. Run `konductro-cursor-setup --url <URL> --token <TOKEN>`, or set KONDUCTRO_URL and KONDUCTRO_CLI_TOKEN in the MCP server environment.';
 
@@ -39,6 +57,7 @@ async function konductroFetch(path, options = {}) {
   const url = `${KONDUCTRO_URL}${path}`;
   const headers = {
     'Authorization': `Bearer ${CLI_TOKEN}`,
+    'X-Konductro-Plugin': PLUGIN_ID,
     ...options.headers,
   };
   // Only set Content-Type and default body for methods that send JSON
@@ -52,13 +71,148 @@ async function konductroFetch(path, options = {}) {
   });
 
   if (!response.ok) {
-    const body = await response.text().catch(() => '');
-    throw new Error(`Konductro API error (${response.status}): ${body}`);
+    const raw = await response.text().catch(() => '');
+    // KON-520: keep the machine-readable code and status on the error. The backend
+    // answers { error, code, details? }, and every tool should branch on CODE rather than
+    // on message text so a wording change server-side cannot break the plugin.
+    //
+    // NOTE this CHANGED err.message. It used to be the whole envelope —
+    // `Konductro API error (404): {"error":"Bug not found","code":"BUG_NOT_FOUND"}` — and
+    // is now just the `error` sentence. Anything that used to sniff the message for a
+    // status or a code no longer matches, so those call sites were moved onto err.code /
+    // err.status (get_bug_for_enrichment and submit_bug_enrichment). If you add a tool,
+    // read the code; do not go back to matching text.
+    let parsed = null;
+    try { parsed = JSON.parse(raw); } catch { /* not JSON — fall through to the raw body */ }
+    const err = new Error(
+      parsed?.error ? parsed.error : `Konductro API error (${response.status}): ${raw}`,
+    );
+    err.status = response.status;
+    err.code = parsed?.code ?? null;
+    // Zod's flatten() on a validation failure. Kept so a refusal can name the offending
+    // field instead of saying "Validation failed" and leaving the agent to guess.
+    err.details = parsed?.details ?? null;
+    throw err;
   }
 
   return response.json();
 }
 
+// ─── KON-520: work-item tools ────────────────────────────────────────────────
+
+/**
+ * Turn a backend refusal into a sentence a developer can act on.
+ *
+ * A bare 403 makes an agent retry or guess. Each of these says what to do instead, and
+ * the setting-related one NAMES the setting, because the developer's next move is to ask
+ * their SDM rather than to try again.
+ *
+ * Keyed on code, never on message text.
+ */
+function refusalText(err) {
+  switch (err.code) {
+    case 'STORY_ACCESS_DENIED':
+      return "Refused: this project's story access is set to planning roles only, so stories here can only be created or edited by an SDM, architect or UX lead. This is a project setting, not something to retry — ask an SDM to make the change, or to open story access for developers. Filing bugs and editing tasks are unaffected.";
+    case 'NOT_YOUR_WORK_ITEM':
+      return 'Refused: you can only change work items assigned to you, that you are the developer on, or that you created. Ask whoever owns it, or ask an SDM to make the change.';
+    case 'STORIES_NOT_DELETABLE':
+      return 'Refused: stories cannot be deleted from the CLI — deleting one removes its tasks with it and cannot be undone. Archive it in Konductro instead.';
+    case 'QA_FILED_BUG':
+      return "Refused: QA filed this bug against a failed test criterion, so it is their record of what went wrong and is not yours to remove. Fix it, or ask QA if it was raised in error.";
+    case 'WORK_ALREADY_STARTED':
+      // Mirrors DELETABLE_STATUSES in work-item-access.service.ts: draft, approved and
+      // in_sprint are all still deletable. Anything past those, or anything with a
+      // branch, is not.
+      return 'Refused: work has already started on this item — it has a branch, or has moved past sprint planning (only items still in draft, approved or in_sprint can be deleted). Deleting it would orphan the branch. Close it out in Konductro instead.';
+    case 'INSUFFICIENT_ROLE':
+      return 'Refused: your Konductro seat is a viewer seat, which is read-only across the whole platform. This is not a project setting — ask an admin to move you to a contributor seat.';
+    case 'READ_ONLY_ROLE':
+      return 'Refused: your role on this project is read-only (viewer or stakeholder), so you cannot create or change work items here. Ask an SDM to give you a writing role on the project.';
+    case 'NOT_PROJECT_MEMBER':
+      return 'Refused: you are not a member of this project, so you cannot create or change work items in it. Ask an SDM to add you to the project team.';
+    default:
+      return null;
+  }
+}
+
+/**
+ * A missing token is a setup problem, not a permission problem — say so differently.
+ *
+ * Uses this plugin's own NOT_CONFIGURED_MESSAGE, which names the `konductro-cursor-setup`
+ * command, rather than telling a Cursor user to go and set environment variables by hand.
+ * The `setup` flag is what workItemCall reads: the message is this repo's, so matching on
+ * its opening words the way the reference plugin does would not survive here.
+ */
+function assertAuthConfigured() {
+  if (!KONDUCTRO_URL || !CLI_TOKEN) {
+    const err = new Error(NOT_CONFIGURED_MESSAGE);
+    err.setup = true;
+    throw err;
+  }
+}
+
+/**
+ * Name the field a validation failure is actually about.
+ *
+ * The backend answers INVALID_BODY with Zod's flatten() attached. Dropping it leaves the
+ * agent holding "Validation failed" with nothing to correct, which it can only respond to
+ * by guessing — so the whole point of validating is lost on the way back.
+ */
+function validationText(err) {
+  const f = err.details?.fieldErrors ?? {};
+  const fields = Object.entries(f)
+    .map(([name, msgs]) => `${name} (${(msgs ?? []).join('; ')})`)
+    .join(', ');
+  const form = (err.details?.formErrors ?? []).join('; ');
+  const parts = [fields, form].filter(Boolean).join(' — ');
+  if (!parts) return err.message;
+  // The backend's sentence for this code is sometimes unpunctuated ('Validation failed'),
+  // so close it before appending rather than running the two together.
+  const lead = /[.!?]$/.test(err.message) ? err.message : `${err.message}.`;
+  return `${lead} Problem with: ${parts}.`;
+}
+
+/**
+ * Every work-item tool answers refusals the same way, so the cases read alike.
+ *
+ * ON isError. A REFUSAL is not an error — it is a correct, final answer to a question the
+ * developer was entitled to ask, and flagging it as an error is what makes an agent retry
+ * it or escalate around it. A genuine FAILURE (bad token, unreachable server, a 500, a
+ * shape the backend rejected) is an error, and is flagged, because the agent should stop
+ * and surface it rather than carry on as if the write landed.
+ *
+ * This is deliberately NOT "whatever the rest of the file does": most tools here flag
+ * nothing at all and report failures as ordinary prose, which is the weaker half of the
+ * convention. The two bug-enrichment tools already make the distinction this follows.
+ */
+async function workItemCall(fn) {
+  try {
+    assertAuthConfigured();
+    return { content: [{ type: 'text', text: await fn() }] };
+  } catch (err) {
+    if (err.status === 401) {
+      return {
+        content: [{ type: 'text', text: `Not authenticated: Konductro rejected the CLI token. It may be expired or revoked — create a new one in Konductro under your profile, then re-run \`konductro-cursor-setup --url <URL> --token <TOKEN>\`. This is a setup problem, not a permissions one.` }],
+        isError: true,
+      };
+    }
+    const refusal = refusalText(err);
+    if (refusal) return { content: [{ type: 'text', text: refusal }] };
+
+    // Setup errors already read as full sentences; only wrap the ones that do not.
+    const text = err.setup
+      ? err.message
+      : `Failed: ${err.code === 'INVALID_BODY' ? validationText(err) : err.message}`;
+    return { content: [{ type: 'text', text }], isError: true };
+  }
+}
+
+/** Resolve the project from the repo's git remote, so no project id is ever asked for. */
+async function projectFromRepo(repoUrl) {
+  const repo = await konductroFetch(`/api/cli/repo-by-url?url=${encodeURIComponent(repoUrl)}`);
+  return repo;
+}
+
 const server = new McpServer({
   name: 'konductro',
   version: '1.0.0',
@@ -91,7 +245,7 @@ server.tool(
     }
 
     const taskList = tasks.map((t, i) =>
-      `${i + 1}. **${t.projectName}** — ${t.phaseName}\n   Client: ${t.clientName}\n   Phase ID: ${t.phaseId}\n   ${t.hasExistingDraft ? '(has existing draft)' : '(new analysis)'}`
+      `${i + 1}. **${t.projectName}** — ${t.phaseName}\n   Client: ${t.clientName}\n   Phase ID: ${t.phaseId}\n   ${t.refreshRequested ? '(refresh requested)' : t.hasExistingDraft ? '(has existing draft)' : '(new analysis)'}`
     ).join('\n\n');
 
     return {
@@ -121,6 +275,25 @@ server.tool(
     if (context.phase.description) contextText += `**Description:** ${context.phase.description}\n`;
     contextText += `\n`;
 
+    // KON-321: a refresh was requested, so this is a revision of an approved
+    // analysis rather than a first pass. Sits above the repositories and the
+    // previous document deliberately — it changes what is being asked for, so
+    // it has to be read before the material it applies to. Absent on a normal
+    // task, in which case the output is exactly what it was before.
+    if (context.refreshContext) {
+      const { requestedBy, message } = context.refreshContext;
+      contextText += `### Refresh Requested\n\n`;
+      contextText += `A refresh of this technical analysis was requested`;
+      if (requestedBy) contextText += ` by ${requestedBy}`;
+      contextText += `.\n\n`;
+      if (message) {
+        contextText += `**Context from the requester:**\n\n${message}\n\n`;
+      } else {
+        contextText += `No further context was given.\n\n`;
+      }
+      contextText += `Revise the existing analysis below rather than starting over.\n\n`;
+    }
+
     if (context.repositories.length > 0) {
       contextText += `### Repositories\n\n`;
       for (const repo of context.repositories) {
@@ -147,6 +320,8 @@ server.tool(
       }
     }
 
+    contextText += renderDocumentTemplate(context.documentTemplate);
+
     return {
       content: [{
         type: 'text',
@@ -156,6 +331,51 @@ server.tool(
   }
 );
 
+/**
+ * The document structure this workspace requires, as the agent must read it.
+ *
+ * APPENDED, never woven into the blob above. Four plugins share that server response and
+ * the agent's prompt is sensitive to its shape, so everything before this point is
+ * byte-identical to what it has always been. A workspace with no template gets an empty
+ * string here and therefore exactly today's context.
+ *
+ * THE WORDING IS IDENTICAL IN ALL FOUR PLUGINS, deliberately. The story this belongs to
+ * requires the same behaviour from Claude, Amazon Q, Codex and Cursor, and four separately
+ * worded prompts is precisely how that stops being true. Change it here and copy it, do
+ * not improve it in one place.
+ *
+ * Standing content is reproduced WORD FOR WORD rather than summarised. It is usually a
+ * compliance clause the workspace requires verbatim, which is the whole reason the field
+ * exists.
+ */
+function renderDocumentTemplate(template) {
+  if (!template) return '';
+
+  let text = `### Required Document Structure\n\n`;
+  text += `This workspace requires technical analysis documents to follow **${template.name}** `;
+  text += `(v${template.version}). Produce these sections, in this order, using these exact headings.\n\n`;
+
+  for (const [index, section] of template.sections.entries()) {
+    text += `${index + 1}. **${section.title}**`;
+    if (section.intent) text += ` — ${section.intent}`;
+    if (section.mustCover) text += ` _(must cover: do not produce the document until you can answer this)_`;
+    text += `\n`;
+    if (section.diagram && section.diagram !== 'none') {
+      const kind = section.diagram === 'any' ? 'a Mermaid diagram of whichever type fits' : `a Mermaid ${section.diagram} diagram`;
+      text += `   Include ${kind} inside this section.\n`;
+    }
+    if (section.standingContent) {
+      text += `   Reproduce this text inside the section, word for word:\n`;
+      text += `   > ${section.standingContent.split('\n').join('\n   > ')}\n`;
+    }
+  }
+
+  text += `\nThis structure replaces any default you would otherwise use. `;
+  text += `The sections marked "must cover" are what your exploration and your questions `;
+  text += `must be able to answer before you produce the document.\n\n`;
+  return text;
+}
+
 // Tool: Submit tech analysis
 server.tool(
   'submit_tech_analysis',
@@ -180,6 +400,216 @@ server.tool(
   }
 );
 
+// ══ DEMAND ANALYSIS ════════════════════════════════════════════════════════
+//
+// The demand-level counterpart of the three tools above. A DEMAND has no project yet —
+// which projects it lands in is decided at IT Eval, from what this analysis finds — so
+// the context carries the whole workspace's repositories and the submission reports
+// which of them the change actually touches.
+
+// Tool: List pending demand analyses
+server.tool(
+  'list_demand_analyses',
+  'List demand technical analyses assigned to you in Konductro. A demand sits above projects: it is a business request that has passed the demand forum and now needs sizing against the real code.',
+  {},
+  async () => {
+    if (!KONDUCTRO_URL || !CLI_TOKEN) {
+      return {
+        content: [{
+          type: 'text',
+          text: 'Konductro is not configured. Please set your Konductro URL and CLI token in the plugin settings.',
+        }],
+      };
+    }
+
+    const { tasks } = await konductroFetch('/api/cli/demand-analyses');
+
+    if (!tasks || tasks.length === 0) {
+      return {
+        content: [{ type: 'text', text: 'No demand analyses assigned to you.' }],
+      };
+    }
+
+    const lines = tasks.map((t) => {
+      const parts = [`### ${t.key} — ${t.title}`];
+      if (t.businessUnit) parts.push(`**Business unit:** ${t.businessUnit}`);
+      if (t.nextSitting) parts.push(`**Back at the forum:** ${new Date(t.nextSitting).toISOString().slice(0, 10)}`);
+      if (t.startWith && t.startWith.length) parts.push(`**Start with:** ${t.startWith.join(', ')}`);
+      if (t.askedFor) parts.push(`**They asked:** ${t.askedFor}`);
+      parts.push(`\`get_demand_analysis_context\` with demandId ${t.key} to load it.`);
+      return parts.join('\n');
+    });
+
+    return {
+      content: [{
+        type: 'text',
+        text: `## Demand analyses assigned to you (${tasks.length})\n\n${lines.join('\n\n')}`,
+      }],
+    };
+  }
+);
+
+// Tool: Load one demand's analysis context
+server.tool(
+  'get_demand_analysis_context',
+  'Load everything needed to run a demand technical analysis: the pitch as the business wrote it, the value case, what the forum asked to have answered, the repositories to start with, and every repository in the workspace.',
+  {
+    demandId: z.string().describe('The demand key (e.g. DEM-4) or its UUID'),
+  },
+  async ({ demandId }) => {
+    if (!KONDUCTRO_URL || !CLI_TOKEN) {
+      return {
+        content: [{
+          type: 'text',
+          text: 'Konductro is not configured. Please set your Konductro URL and CLI token in the plugin settings.',
+        }],
+      };
+    }
+
+    const ctx = await konductroFetch(`/api/cli/demand-analyses/${demandId}/context`);
+    const d = ctx && ctx.demand;
+    if (!d) {
+      return {
+        content: [{
+          type: 'text',
+          text: `No demand context came back for ${demandId}. Check the key, and that the analysis is assigned to you.`,
+        }],
+      };
+    }
+
+    const cost = Object.entries(d.cost || {})
+      .filter(([, v]) => v)
+      .map(([k, v]) => `- **${k}:** ${v}`)
+      .join('\n') || '- Not given';
+
+    // THE PROJECT ID IS THE POINT OF THIS LIST, not decoration. `submit_demand_analysis`
+    // takes a `projectId` per proposed phase, and its description says to take it from
+    // here. Rendering only the project NAME left the analyst nowhere to get it: either
+    // the phase is submitted with no project, so the green light creates no real Phase
+    // and IT Eval prefills with nothing, or the agent invents a uuid and the whole
+    // submission is refused with PROJECT_NOT_FOUND.
+    const repos = (ctx.repositories || [])
+      .map((r) => `- \`${r.name}\` (${r.projectName}${r.type ? `, ${r.type}` : ''}) — ${r.url}\n  projectId: \`${r.projectId}\``)
+      .join('\n') || '- None linked to any project yet';
+
+    const conversation = (ctx.conversation || [])
+      .map((c) => `- **${c.by}**${c.kind === 'amendment' ? ' (amendment)' : ''}: ${c.body}`)
+      .join('\n');
+
+    // THE WORKSPACE'S OWN QUESTIONS, which the block above does not carry.
+    //
+    // The fields rendered above are the nine Konductro ships. A workspace that added
+    // "Which regulator requires this?" has that question and its answer here and
+    // NOWHERE ELSE in this payload, so without this the analysis never learns it was
+    // asked — the one thing the whole templating feature exists for.
+    //
+    // Read off the PINNED template, so a question a later template deleted still shows
+    // on the demands that answered it. Unanswered questions are kept rather than
+    // dropped: that the forum asked and got nothing is itself worth knowing.
+    const tpl = ctx.template;
+    const templateBlock = tpl
+      ? [
+          `## The form they filled in — ${tpl.name} v${tpl.version}`,
+          '',
+          ...(tpl.sections || []).flatMap((section) => [
+            `### ${section.name}`,
+            ...(section.help ? ['', `_${section.help}_`] : []),
+            '',
+            ...(section.questions || []).map((q) =>
+              `**${q.question}**\n\n${q.answer || '_Not answered._'}\n`
+            ),
+          ]),
+        ].join('\n')
+      : '';
+
+    return {
+      content: [{
+        type: 'text',
+        text: [
+          `# ${d.key} — ${d.title}`,
+          '',
+          `**Raised by:** ${d.raisedBy}${d.businessUnit ? ` (${d.businessUnit})` : ''}`,
+          '',
+          '## What they need',
+          d.need,
+          '',
+          '## What happens today',
+          d.currentState || 'Not given',
+          '',
+          '## Who it affects',
+          [d.affects, d.affectsWho].filter(Boolean).join(' — ') || 'Not given',
+          '',
+          '## What it costs to not have it',
+          cost,
+          '',
+          '## Tied to a date',
+          d.date?.type ? `${d.date.type}${d.date.by ? ` — ${String(d.date.by).slice(0, 10)}` : ''}${d.date.why ? ` (${d.date.why})` : ''}` : 'No fixed date',
+          '',
+          '## How they would know it worked',
+          d.successLooksLike || 'Not given',
+          '',
+          '## What the forum asked you to answer',
+          ctx.askedFor || 'Nothing specific. Answer the pitch.',
+          '',
+          '## Where to start looking',
+          (ctx.startWith && ctx.startWith.length) ? ctx.startWith.map((r) => `\`${r}\``).join(', ') : 'Nothing named — use your judgement.',
+          '',
+          '## Every repository in this workspace',
+          'The starting point above is a hint, not a boundary. Report what the change ACTUALLY touches.',
+          '',
+          repos,
+          templateBlock ? `\n${templateBlock}` : '',
+          conversation ? `\n## Conversation on the demand\n${conversation}` : '',
+        ].join('\n'),
+      }],
+    };
+  }
+);
+
+// Tool: Submit a demand analysis
+server.tool(
+  'submit_demand_analysis',
+  'Push a finished demand technical analysis back to Konductro: what you found, which repositories the change actually touches, and the phase breakdown you propose. The breakdown is a PROPOSAL — the demand forum decides at IT Eval.',
+  {
+    demandId: z.string().describe('The demand key (e.g. DEM-4) or its UUID'),
+    summary: z.string().describe('What the analysis found, in markdown. What is already there, what has to change, the risks, and the assumptions the estimate rests on.'),
+    // BOTH OF THESE ARE CLEARED WHEN OMITTED, server-side and deliberately: a
+    // resubmission that dropped them used to keep the OLD proposal while the repos
+    // beside it reset to empty, leaving an analysis half from one run and half from
+    // another — which IT Eval then prefills from. So a second submission has to send
+    // all three fields or lose the two it leaves out.
+    foundRepos: z.array(z.string()).optional().describe('The repositories the change actually touches, by name. Not the ones you were told to start with. Resubmitting without this CLEARS it.'),
+    proposedPhases: z.array(z.object({
+      name: z.string().describe('What this phase delivers'),
+      projectId: z.string().uuid().optional().describe('The project it lands in, from the context. Omit if it genuinely belongs nowhere yet.'),
+      points: z.number().int().min(0).max(1000).describe('Story points for this phase alone. Never send a total; Konductro derives it.'),
+      why: z.string().optional().describe('Why it is its own phase rather than part of another'),
+    })).optional().describe('The phases you propose. A phase belongs to ONE project; work spanning two projects is two phases. Resubmitting without this CLEARS it.'),
+  },
+  async ({ demandId, summary, foundRepos, proposedPhases }) => {
+    if (!KONDUCTRO_URL || !CLI_TOKEN) {
+      return {
+        content: [{
+          type: 'text',
+          text: 'Konductro is not configured. Please set your Konductro URL and CLI token in the plugin settings.',
+        }],
+      };
+    }
+
+    const result = await konductroFetch(`/api/cli/demand-analyses/${demandId}/submit`, {
+      method: 'POST',
+      body: JSON.stringify({ summary, foundRepos, proposedPhases }),
+    });
+
+    return {
+      content: [{
+        type: 'text',
+        text: `## Demand analysis submitted\n\n${result.message}\n\n- Demand: ${result.key}\n- Submitted: ${result.submittedAt}\n\nThe demand forum has been notified and can now record the IT Eval.`,
+      }],
+    };
+  }
+);
+
 // Tool: List pending decomposition tasks
 server.tool(
   'list_decomposition_tasks',
@@ -505,6 +935,12 @@ server.tool(
       text += `### Context Pack\n\n${ctx.ticket.contextPack}\n\n`;
     }
 
+    // Developer Notes — present when context is fetched on a story itself. For a
+    // task, the notes that matter are the parent story's, rendered below.
+    if (ctx.ticket.developerNotes) {
+      text += `### Developer Notes\n\n${ctx.ticket.developerNotes}\n\n`;
+    }
+
     // Parent Story
     if (ctx.parent) {
       text += `### Parent Story: ${ctx.parent.ticketKey} — ${ctx.parent.title}\n\n`;
@@ -517,6 +953,10 @@ server.tool(
       if (ctx.parent.contextPack) {
         text += `**Story Context Pack:**\n${ctx.parent.contextPack}\n\n`;
       }
+      // Story-level context accumulated by whoever worked the story's other tasks.
+      if (ctx.parent.developerNotes) {
+        text += `**Parent Story, Developer Notes:**\n${ctx.parent.developerNotes}\n\n`;
+      }
     }
 
     // Children tasks
@@ -562,6 +1002,153 @@ server.tool(
   }
 );
 
+// Tool: Append a developer note to a story (KON-314)
+server.tool(
+  'append_story_developer_note',
+  "Append a note to a story's developer notes in Konductro, so context you worked out on one task is there for whoever picks up the next task on the same story. Notes live on the STORY, not the task: pass the parent story's key, which get_ticket_context prints in its Parent Story heading. Pass the current task's key as taskKey so the entry is attributable. Send only your new note — the endpoint appends it, and Konductro stamps the author, timestamp and task itself, so do not include a heading, a timestamp, a separator, or any notes you read earlier.",
+  {
+    storyId: z.string().describe('The story to append to — key (e.g. KON-283) or UUID. Not a task.'),
+    note: z.string().describe('The new note only, as markdown. No heading, timestamp or separator.'),
+    taskKey: z.string().optional().describe("The key of the task this note came from (e.g. KON-314), when there is one"),
+  },
+  async ({ storyId, note, taskKey }) => {
+    const result = await konductroFetch(`/api/cli/tickets/${storyId}/developer-notes`, {
+      method: 'POST',
+      body: JSON.stringify({ note, taskKey }),
+    });
+
+    // Not echoing result.developerNotes: it is the whole accumulated blob, and
+    // repeating it here invites a later call to send it back as a "new" note.
+    return {
+      content: [{
+        type: 'text',
+        text: `Note appended to ${result.ticketKey}'s developer notes.`,
+      }],
+    };
+  }
+);
+
+// Tool: Create a work item
+server.tool(
+  'create_work_item',
+  "Create a story, task or bug in the Konductro project this repository belongs to. Anything created this way lands in DRAFT and still needs an SDM's approval before it can be worked — say so when you report back, so nobody thinks it is ready to start. A task needs a parent story, and is created in the repository repoUrl resolves to; a bug needs no parent and is filed standalone. Creating STORIES is governed by the project's story access setting and may be refused; filing bugs and creating tasks are not affected by it. Pass the repository's git remote (git remote get-url origin) — the project is resolved from it, never asked for.",
+  {
+    repoUrl: z.string().describe('The git remote URL of this repository (run: git remote get-url origin)'),
+    kind: z.enum(['story', 'task', 'bug']).describe('What to create'),
+    title: z.string().describe('A short title, as a person would write it'),
+    description: z.string().describe('What this is and why, in markdown'),
+    acceptanceCriteria: z.array(z.string()).optional().describe('Observable behaviour, one per item. Omit for a bug unless you have them.'),
+    parentKey: z.string().optional().describe('For a TASK, the parent story key (e.g. KON-451). ONLY a task may have a parent. A story or a bug sent with a parentKey is REFUSED and nothing is created, rather than being filed top-level as though it had worked.'),
+    repositoryId: z.string().optional().describe('For a TASK, the repository UUID it will be built in. Leave this out — it defaults to the repository repoUrl resolves to, which is the one you are standing in. Only set it for a task that will be built in a DIFFERENT repository on the same project, and then you need that repo\'s UUID from Konductro.'),
+  },
+  async ({ repoUrl, kind, title, description, acceptanceCriteria, parentKey, repositoryId }) => workItemCall(async () => {
+    // The backend's body schema DECLARES parentKey, so .strict() does not reject it — it
+    // is accepted and then dropped for anything that is not a task, because the route
+    // reads it only inside the task branch and calls createBug / createStory without it
+    // (routes/cli.ts). The item lands top-level and the 201 reports success, so asking
+    // for it under a story and being told it worked is exactly what happens. Refuse
+    // instead: a refusal is recoverable in the next turn, a misfiled item is found later
+    // by someone else, if at all.
+    //
+    // The two cases are dropped by the same code path but for different reasons, so the
+    // remedy differs and the message branches. A bug COULD have a parent — QA files bugs
+    // against the tested story that way — this endpoint just does not wire it through. A
+    // story could not: the hierarchy is story → task, so nothing sits above a story ever,
+    // and an agent sending one almost certainly meant to create a task.
+    if (kind !== 'task' && parentKey) {
+      const why = kind === 'bug'
+        ? `Konductro only parents a bug to a story when QA files it against a failed test criterion; a bug created from the CLI is always standalone in the project's Bugs phase. Re-run without parentKey, and name ${parentKey} in the description so the link to it is not lost.`
+        : `A story is top-level by definition — the hierarchy is story → task, so nothing sits above a story. If you meant to add work under ${parentKey}, re-run with kind "task". If you meant a new story, re-run without parentKey.`;
+      return `Refused: only a task can be created under a parent, and NOTHING WAS CREATED. ${why}`;
+    }
+
+    const repo = await projectFromRepo(repoUrl);
+
+    // Creating a task was a dead end without this. The backend requires repositoryId as a
+    // UUID, and nothing a developer can reach hands one out — get_decomposition_context
+    // is the only tool that returns one, and that needs an assigned decomposition task
+    // you do not have. So the agent was asked for a value it could not obtain, and a
+    // guess came back as a bare "Validation failed".
+    //
+    // It was in hand the whole time: repo-by-url returns the repository row (id, name,
+    // repoUrl, repoType, stacks, projectId, project) and the id was being discarded.
+    // Defaulting to it is also the right answer rather than merely an available one — the
+    // task is being written from inside the repo it will be built in.
+    //
+    // Tasks only. createStory ignores it, and defaulting it on a bug would silently start
+    // attributing bugs to a repository they were not attributed to before.
+    const resolvedRepositoryId = kind === 'task' ? (repositoryId ?? repo.id) : repositoryId;
+
+    const created = await konductroFetch(`/api/cli/projects/${repo.projectId}/work-items`, {
+      method: 'POST',
+      body: JSON.stringify({ kind, title, description, acceptanceCriteria, parentKey, repositoryId: resolvedRepositoryId }),
+    });
+    // Returning the id rather than the number alone. A key is PREFIX-NUMBER, the prefix is
+    // nowhere in this tool's reach (repo-by-url does not return ticketPrefix), so printing
+    // the number and pointing at "its key" invited the agent to guess one. resolveTicketId
+    // matches prefix+number across the whole TENANT, not within the project, so a guessed
+    // prefix does not 404 — it resolves to another project's ticket of the same number,
+    // and the next update_work_item edits that one instead. The id closes it off: the UUID
+    // branch of resolveTicketId short-circuits with no lookup at all.
+    return `Created #${created.ticketNumber} — "${created.title}" (${created.kind}) in ${repo.project?.name ?? 'the project'}.\n\nid: ${created.id}\n\nIt is in ${created.status.toUpperCase()} and needs an SDM to approve it before it can be worked on. Use THAT id with get_ticket_context, update_work_item or delete_work_item. Do not build a key from #${created.ticketNumber} — the project's ticket prefix is not returned here, and a guessed prefix silently resolves to a different project's item of the same number rather than failing.`;
+  })
+);
+
+// Tool: Update a work item
+server.tool(
+  'update_work_item',
+  "Change the title, description or acceptance criteria of a work item you own in Konductro — one assigned to you, that you are the developer on, or that you created. THESE THREE FIELDS ARE ALL YOU CAN CHANGE: status, sprint, assignee and everything else are deliberately not available here and must be changed in Konductro. Editing a STORY is governed by the project's story access setting and may be refused, or may be applied and then held for an SDM to review; editing a task is not affected by it. Send only the fields you are actually changing.",
+  {
+    key: z.string().describe('The work item key (e.g. KON-451) or UUID'),
+    title: z.string().optional().describe('The new title'),
+    description: z.string().optional().describe('The new description, in markdown'),
+    acceptanceCriteria: z.array(z.string()).optional().describe('The FULL new list, not just the additions — it replaces what is there'),
+  },
+  async ({ key, title, description, acceptanceCriteria }) => workItemCall(async () => {
+    const body = {};
+    if (title !== undefined) body.title = title;
+    if (description !== undefined) body.description = description;
+    if (acceptanceCriteria !== undefined) body.acceptanceCriteria = acceptanceCriteria;
+    if (Object.keys(body).length === 0) {
+      return 'Nothing to change — pass at least one of title, description or acceptanceCriteria.';
+    }
+
+    const result = await konductroFetch(`/api/cli/tickets/${encodeURIComponent(key)}/work-item`, {
+      method: 'PATCH',
+      body: JSON.stringify(body),
+    });
+
+    // Deliberately NOT echoing the updated values back. Returning the item invites the
+    // next call to send them again as "new" values, re-submitting fields nobody changed
+    // and raising a review for a no-op. Same reason append_story_developer_note does not
+    // return the notes blob.
+    // `changed` echoes the fields that were WRITTEN, not the ones that turned out to
+    // differ — the server returns Object.keys of what it applied (routes/cli.ts). So
+    // re-sending a title with its existing value still reports "changed: title". Do not
+    // read it as a diff.
+    const changed = (result.changed ?? Object.keys(body)).join(', ');
+    let text = `Updated ${key} (#${result.ticketNumber}) — changed: ${changed}.`;
+    if (result.awaitingReview) {
+      text += '\n\nThis change is APPLIED but now waiting for an SDM to approve or reject it, because this project reviews story changes. Until it is resolved the story will not move to Ready for QA, even if every task is done. If it is rejected the previous values come back and you will be notified.';
+    }
+    return text;
+  })
+);
+
+// Tool: Delete a work item
+server.tool(
+  'delete_work_item',
+  "Delete a task or a bug from Konductro that has not been started. Bugs count: Konductro stores a bug as a task, so a developer's own unstarted bug can be deleted here. Stories cannot — deleting one takes its tasks with it and there is no restore, so archive a story in Konductro instead. Neither can a bug QA filed against a failed test criterion, which is part of that test record rather than yours. Nothing that has started can be deleted by anyone: that means anything carrying a branch, or anything past sprint planning, since only draft, approved and in_sprint items still qualify. Close those out in Konductro instead. Beyond that you may delete an item you are assigned to, are the developer on, or created; an SDM, architect or UX lead on the project may delete any item that qualifies. This is permanent and there is no undo, so be sure the developer asked for it.",
+  {
+    key: z.string().describe('The task or bug key (e.g. KON-452) or UUID'),
+  },
+  async ({ key }) => workItemCall(async () => {
+    const result = await konductroFetch(`/api/cli/tickets/${encodeURIComponent(key)}/work-item`, { method: 'DELETE' });
+    const extra = result.deleted > 1 ? ` (${result.deleted} rows, including its linked records)` : '';
+    return `Deleted ${key}${extra}. This cannot be undone.`;
+  })
+);
+
 // Tool: Start work on a ticket
 server.tool(
   'start_work',
@@ -958,7 +1545,13 @@ server.tool(
 
       return { content: [{ type: 'text', text }] };
     } catch (err) {
-      const msg = err.message?.includes('BUG_NOT_FOUND') || err.message?.includes('404')
+      // KON-520: this used to sniff err.message for 'BUG_NOT_FOUND' / '404', which worked
+      // only because the message was the whole raw envelope. konductroFetch now sets
+      // message to the backend's `error` sentence, so that match silently stopped firing
+      // and a missing bug reported as a generic failure. Read the code and the status
+      // instead — both are on the error and neither depends on wording.
+      const notABug = err.code === 'BUG_NOT_FOUND' || err.status === 404;
+      const msg = notABug
         ? `Ticket ${ticketId} not found or is not a bug.`
         : `Failed to load bug context: ${err.message}`;
       return { content: [{ type: 'text', text: msg }], isError: true };
@@ -994,9 +1587,11 @@ server.tool(
         : 'No new enrichment applied (fields may already exist on the ticket).';
       return { content: [{ type: 'text', text: applied }] };
     } catch (err) {
-      const msg = err.message?.includes('BUG_NOT_FOUND') || err.message?.includes('404')
+      // Same fix as get_bug_for_enrichment above — match on err.code / err.status, not
+      // on message text, which konductroFetch no longer formats the way this expected.
+      const msg = (err.code === 'BUG_NOT_FOUND' || err.status === 404)
         ? `Ticket ${ticketId} not found or is not a bug.`
-        : err.message?.includes('INVALID_ENRICHMENT')
+        : err.code === 'INVALID_ENRICHMENT'
         ? 'At least one enrichment field must be provided.'
         : `Failed to submit enrichment: ${err.message}`;
       return { content: [{ type: 'text', text: msg }], isError: true };

package/skills/demand-analysis.mdc

@@ -0,0 +1,107 @@
+---
+description: USE WHEN an architect has been assigned a Konductro DEMAND technical analysis — a business request that has passed the demand forum and needs sizing against the real code before the forum will commit to it
+globs:
+alwaysApply: false
+---
+
+# Konductro Demand Analysis
+
+A demand is a business request that sits ABOVE projects. It has passed the demand forum,
+and the forum will not commit to it until somebody has read the actual code and said what
+it entails. That is this job.
+
+## What makes this different from a phase's technical analysis
+
+A phase already belongs to a project, so its repositories are known. **A demand does not.**
+Which projects the work lands in is decided at IT Eval, FROM WHAT YOU FIND. So:
+
+- The context lists **every repository in the workspace**, not a project's few.
+- The "start with" list is a hint from whoever assigned it. It is not a boundary, and it
+  is regularly wrong: the work turns out to be in a repository nobody expected.
+- You report which repositories the change **actually touches**. That is what the forum
+  reads, and it is stored separately from the hint you were given.
+
+## Workflow
+
+### Step 1: See what is assigned
+
+Call `list_demand_analyses`. Present the list and ask which one to work on. Each shows
+what the forum asked to have answered and when it is next sitting — that date is the
+deadline, so say it out loud.
+
+### Step 2: Load the context
+
+Call `get_demand_analysis_context` with the demand key. Read the whole thing before
+touching any code. It carries:
+
+- The pitch, in the business's own words, and what happens today
+- The value case: who it affects, and what it costs to not have it
+- **The form they actually filled in**, which is the workspace's own template rather
+  than a fixed set of questions. A workspace that asks "Which regulator requires this?"
+  has that question and its answer here and nowhere else, and it is usually the one that
+  changes the estimate. Read it.
+- What the forum specifically asked you to answer
+- Every repository in the workspace, with its project
+
+**Say the value case back to the user in one line.** An estimate has to be proportionate
+to the thing being bought, and this is the only place that number appears.
+
+### Step 3: Read the code
+
+The repositories are on this machine. Use Glob, Grep and Read. Konductro never clones
+anything and neither do you: if a repository named in the context is not present locally,
+say so rather than guessing at it.
+
+Start with the repositories you were pointed at, then follow the work wherever it goes.
+
+What you are trying to establish, in this order:
+
+1. **What already exists.** Half of every demand turns out to be built. Say what is there
+   before you say what is needed.
+2. **What actually has to change**, per repository, concretely enough that somebody could
+   argue with it.
+3. **What is in the way.** Missing data, an integration nobody has written, a migration
+   with no way back.
+4. **What the estimate rests on.** Every assumption you make is a way the number could be
+   wrong, and the forum is told which one when it is.
+
+### Step 4: Propose the phases
+
+This is the part the forum needs most, and the part it cannot do itself.
+
+- **A phase belongs to ONE project.** Work spanning two projects is two phases. This is
+  not a formality: each phase becomes a real Phase in that project when the demand is
+  green lit.
+- **Order them by what has to land first.** If phase two cannot start until phase one is
+  deployed, say so in its `why`.
+- **Points per phase, never a total.** Konductro derives the total. Sending your own is
+  how the headline number and the breakdown behind it end up disagreeing.
+- **A phase with no obvious home** is allowed: omit `projectId` and say why in the `why`.
+  A visible gap beats a phase filed in whichever project came first.
+
+### Step 5: Submit
+
+Call `submit_demand_analysis` with:
+
+- `summary` — what you found. Structure it as: what exists, what has to change, risks,
+  assumptions. Markdown.
+- `foundRepos` — the repositories the change actually touches. Not the hint you were given.
+- `proposedPhases` — the breakdown above.
+
+The forum is notified and records the IT Eval from your proposal. They can change any of
+it; you are advising, not deciding.
+
+**If you submit a second time, send all three again.** `foundRepos` and `proposedPhases`
+are cleared when they are left out, deliberately: a resubmission that kept the old
+proposal beside freshly reset repositories would be half one run and half another, and
+IT Eval prefills from it.
+
+## The bar
+
+**Never estimate something you have not read.** An unfamiliar name is a reason to go and
+look, never a reason to assume it is small. If a repository you need is not on this
+machine, the honest output is a summary that says which one and what it blocks — not a
+number with a shrug behind it.
+
+**Say what you did not check.** The forum is about to commit money against this. A gap you
+name costs an hour; a gap you paper over costs the quarter.

package/skills/technical-analysis.mdc

@@ -20,11 +20,20 @@ Call `get_task_context` with the phase ID. This loads:
 - The approved requirements document (what needs to be built)
 - Project and client context
 - Repository information
+- A "Refresh Requested" section, when someone has asked for an existing analysis
+  to be redone. Read it first: it carries the requester's reason, and the job is
+  to revise the previous analysis rather than start from scratch.
 
 Share a summary of the requirements with the user and confirm you're ready to begin.
 
 ### Step 3: Explore the Codebase
 
+**If the context carried a "Required Document Structure", that is your brief.** Every section in it is something you must be able to answer by the end of this step, and the ones marked "must cover" are not optional. Explore with those sections in mind rather than working through the generic list below and hoping it covers them — a workspace that asks for a Regulatory Impact section is telling you what to go and find out, and nothing in the generic list will lead you there.
+
+Where the structure asks for something the generic list does not cover, go and look for it. Where it omits something, you do not need to chase it.
+
+If no structure was supplied, use the list below as-is.
+
 Analyse the local codebase using file reading and search tools:
 - **Project structure** — folder layout, module organisation
 - **Tech stack** — frameworks, versions, build tools
@@ -40,6 +49,10 @@ Discuss findings with the user as you go. Ask clarifying questions.
 
 ### Step 4: Impact Analysis
 
+**Before moving on, check yourself against the required structure.** Take each section, and each "must cover" section especially, and ask whether you could write it now from what you have found. Where you could not, that is a question for the user or another pass over the codebase — ask it now rather than discovering the gap while writing the document, when the honest options are guessing or going back.
+
+This is the step that makes the structure mean something. Producing the right headings over content that does not answer them is worse than the default document, because it looks like compliance.
+
 Based on the requirements and your codebase exploration, assess:
 - **What needs to change** — which files, modules, or services
 - **What needs to be created** — new components, services, APIs
@@ -49,7 +62,12 @@ Based on the requirements and your codebase exploration, assess:
 
 ### Step 5: Produce the Document
 
-Produce a structured technical analysis document including:
+**If the context carried a "Required Document Structure", follow it exactly** — those sections, in that order, under those headings. It replaces the default list below rather than supplementing it: do not add the default sections alongside it, and do not reorder it to something you find more natural. Where a section carries standing content, reproduce that text word for word; it is usually a clause the workspace is required to publish, and paraphrasing it defeats the point of it being there. Where a section asks for a diagram, draw one, as Mermaid, inside that section.
+
+A document produced here must be indistinguishable from one produced for the same workspace in Konductro itself. That is the whole purpose of the structure being sent.
+
+**If no structure was supplied**, use this default list:
+
 1. **Codebase Overview** — what exists today
 2. **Technical Stack** — frameworks, versions, build tools, deployment
 3. **Architecture Patterns** — structure, key design decisions
@@ -72,3 +90,4 @@ Ask the user to review the document. When approved, call `submit_tech_analysis`
 - Be thorough but focused — analyse what's relevant to the requirements
 - Ask the user questions — they know the codebase context you don't
 - Produce a complete, standalone document an architect can use without additional context
+- When a required document structure is supplied, it wins over anything in this file. It is the workspace's own standard, and your job is to meet it, not to improve on it