amsd-pipeline-shared 0.5.16 → 0.5.17

package/docs/gateway-baseline-2.0.80.md5

@@ -235,3 +235,4 @@ ff9ea38d594f181363c40295ea42012a  prompts/templates/writer-plan-section.json
 28adf858dafddc3ef7bb03d3686dfe6d  scripts/lib/project-prompt-contract.js
 4120de0abec9f84c3b0fa98cd2584233  scripts/lib/worktree-rungs.sh
 515f80e7a9228cdfbc39e71c06066d95  scripts/lib/story-attempt.sh
+6a31e809386b4114794bb773c850b46b  scripts/lib/producers/fix-plan.js

package/docs/gateway-files.txt

@@ -223,6 +223,7 @@ scripts/lib/plan-of-record.sh
 scripts/lib/plan-scope.js
 scripts/lib/preflight.sh
 scripts/lib/prelaunch.js
+scripts/lib/producers/fix-plan.js
 scripts/lib/project-prompt-contract.js
 scripts/lib/qa-gate-evidence.sh
 scripts/lib/relative-paths.js

package/orchestrations/prompts/templates/detective-overall-plan-given.json

@@ -3,7 +3,8 @@
     "Operator, 2026-10-06: one plan for the story, written once and passed to every codeline as a shared artefact.",
     "The first detective writes it (detective-overall-plan); the detective of every later codeline is given it here and",
     "investigates its own codeline's part, rather than planning the story again from one codeline's view.",
-    "2026-10-06, real-model rounds: given a plan that gave it no change, a consumer lane marked its lock file and locale files as requiring change."
+    "2026-10-06, real-model rounds: given a plan that gave it no change, a consumer lane marked its lock file and locale files as requiring change.",
+    "v2 (operator, 2026-10-22: \"If the plan agent is not given proper instructions to provide package updates then there is your rc\"): a consumer's plan names the update that brings in the provider's release, and any change of its own its criteria need — run 11's plan gave gotransit 'no change', it never received cx-shared 8.12.0, and its Writer looped."
   ],
   "description": "Composed into the code-graph detective's prescription once the story has an overall plan: work this codeline's part of it, and say plainly where this codeline's code contradicts it.",
   "id": "detective-overall-plan-given",
@@ -14,6 +15,6 @@
     "__OVERALL_PLAN__",
     "__THIS_CODELINE__"
   ],
-  "version": 1,
-  "body": "\nTHIS STORY ALREADY HAS ITS PLAN, written by the first investigation for every codeline it is worked in. You are investigating codeline \"__THIS_CODELINE__\": locate the fix sites for ITS part of the plan below, and nothing the plan gives to another codeline.\n__OVERALL_PLAN__\nWhere the plan gives this codeline no change of its own, none of your fix sites requires a change — receiving the provider's release (manifest, lock file, install) is not this codeline's work in this story.\nThe plan is the story's, not a lead to re-derive. Where this codeline's own code contradicts it — a use of the changed code the plan does not list, a part that cannot be done as stated — say so in the fix site's reason, naming what you found; do not write a different plan.\n"
+  "version": 2,
+  "body": "\nTHIS STORY ALREADY HAS ITS PLAN, written by the first investigation for every codeline it is worked in. You are investigating codeline \"__THIS_CODELINE__\": locate the fix sites for ITS part of the plan below, and nothing the plan gives to another codeline.\n__OVERALL_PLAN__\nWhere this codeline consumes the provider's package, the plan's `update` for it (the lock file or its own update script, within its declared range) is this codeline's work, and so is its `change`, where it has one. Where the plan gives it no change of its own beyond the update, none of your other fix sites requires a change — and a note that a file needs no edit is never written into that file.\nThe plan is the story's, not a lead to re-derive. Where this codeline's own code contradicts it — a use of the changed code the plan does not list, a part that cannot be done as stated — say so in the fix site's reason, naming what you found; do not write a different plan.\n"
 }

package/orchestrations/prompts/templates/detective-overall-plan.json

@@ -11,7 +11,8 @@
     "2026-10-06, real-model rounds: the plan wrote a consumer's change as \"none in shared code; update installed package within range\", and that consumer's lane then prescribed its lock file.",
     "",
     "2026-10-06, real-model round: a consumer's change read \"none (dependency bump only; review own toast messages)\", and that lane then changed its locale file.",
-    "2026-10-06: a shared codeline is worked once per release line the plan names (lib/release-lines.sh); the plan says which line the codeline's own base is on, so no version arithmetic is written into the engine."
+    "2026-10-06: a shared codeline is worked once per release line the plan names (lib/release-lines.sh); the plan says which line the codeline's own base is on, so no version arithmetic is written into the engine.",
+    "v5 (operator, 2026-10-22: \"If the plan agent is not given proper instructions to provide package updates then there is your rc\"): a consumer's plan names the update that brings in the provider's release, and any change of its own its criteria need — run 11's plan gave gotransit 'no change', it never received cx-shared 8.12.0, and its Writer looped."
   ],
   "description": "Composed into every code-graph detective's prescription: before naming fix sites, write the one plan the whole story is worked from — every codeline's part, every consumer's blast radius, every release line.",
   "id": "detective-overall-plan",
@@ -21,6 +22,6 @@
   "placeholders": [
     "__PLAN_CODELINES__"
   ],
-  "version": 4,
-  "body": "\nTHE OVERALL PLAN. This story is worked in the codelines below, and every one of them is worked from the plan you write here — it is the one plan for the whole story, not this codeline's notes. You can read each codeline at the location given.\n__PLAN_CODELINES__\nEstablish, by reading the code, not by assuming:\n1. EACH CODELINE'S PART: what it must change in its own code, or that it changes nothing — and the order the codelines must be worked in, when one needs another's change first.\n2. FOR EVERY PACKAGE ONE OF THESE CODELINES PROVIDES AND ANOTHER CONSUMES: the BLAST RADIUS — in each consumer, the files and calls that reach the code being changed, read in that consumer; and whether the change alters anything those calls depend on.\n3. THE RELEASE LINES the change must ship on, so that every consumer receives it through the range it ALREADY declares. A consumer's declared range is never changed by this story. Say how each consumer receives its release: within its declared range (an update the range already allows) — never by installing the latest release, which can move the range; read what a consumer's own scripts do before naming one. Each line is worked on its own branch from its base; say for each whether the provider codeline's own base is already on it (onCodelineBase). One line per distinct line the consumers' ranges require; for each, the base it is cut from (the newest existing release on that line, from the release facts above) and the version it ships as.\n\nWrite the plan as ONE JSON object between these tags, before your fix-site answer:\n<OVERALL_PLAN>\n{\"codelines\":[{\"codeline\":\"<name>\",\"part\":\"<what it changes in its own code, or that it changes nothing and how it receives the change>\",\"order\":1}],\"packages\":[{\"package\":\"<name, as its manifest declares it>\",\"providedBy\":\"<codeline>\",\"releaseLines\":[{\"line\":\"<the release line>\",\"base\":\"<the existing release it is cut from>\",\"version\":\"<the version it ships as>\",\"onCodelineBase\":<true if the provider codeline's own base is on this line — even when newer releases were cut on it since; the change merges forward onto it. false only for a different, older line>,\"carries\":\"<what this line carries: for a line off the codeline's own base, the change made on the codeline's own line, ported in full: the story's whole change on the codeline's own line — what is already there and what this plan adds — every part of it, adapted where this line's code differs>\"}],\"consumers\":[{\"codeline\":\"<codeline>\",\"declaredRange\":\"<as its manifest declares it>\",\"receivesVia\":\"<the version, from the release lines above>\",\"usage\":[\"<file>: <how it reaches the code being changed>\"],\"change\":\"<exactly none, or the change this consumer makes in its OWN code for this story — never none plus something to do or review>\"}]}]}\n</OVERALL_PLAN>\nReceiving the provider's release is never a consumer's change in this story — not its manifest, not its lock file, not an install: that release does not exist until the provider ships it.\nYour fix sites, after the plan, are files of THIS codeline only. Another codeline's files belong in the plan — its part and its usage — never among your fix sites.\nA story worked in ONE codeline writes the same plan: one entry under codelines, and packages empty unless that codeline provides one another codeline consumes.\n"
+  "version": 5,
+  "body": "\nTHE OVERALL PLAN. This story is worked in the codelines below, and every one of them is worked from the plan you write here — it is the one plan for the whole story, not this codeline's notes. You can read each codeline at the location given.\n__PLAN_CODELINES__\nEstablish, by reading the code, not by assuming:\n1. EACH CODELINE'S PART: what it must change in its own code, or that it changes nothing — and the order the codelines must be worked in, when one needs another's change first.\n2. FOR EVERY PACKAGE ONE OF THESE CODELINES PROVIDES AND ANOTHER CONSUMES: the BLAST RADIUS — in each consumer, the files and calls that reach the code being changed, read in that consumer; and whether the change alters anything those calls depend on.\n3. THE RELEASE LINES the change must ship on, so that every consumer receives it through the range it ALREADY declares. A consumer's declared range is never changed by this story. Say how each consumer receives its release: within its declared range (an update the range already allows) — never by installing the latest release, which can move the range; read what a consumer's own scripts do before naming one. Each line is worked on its own branch from its base; say for each whether the provider codeline's own base is already on it (onCodelineBase). One line per distinct line the consumers' ranges require; for each, the base it is cut from (the newest existing release on that line, from the release facts above) and the version it ships as.\n\nWrite the plan as ONE JSON object between these tags, before your fix-site answer:\n<OVERALL_PLAN>\n{\"codelines\":[{\"codeline\":\"<name>\",\"part\":\"<what it changes in its own code, or that it changes nothing and how it receives the change>\",\"order\":1}],\"packages\":[{\"package\":\"<name, as its manifest declares it>\",\"providedBy\":\"<codeline>\",\"releaseLines\":[{\"line\":\"<the release line>\",\"base\":\"<the existing release it is cut from>\",\"version\":\"<the version it ships as>\",\"onCodelineBase\":<true if the provider codeline's own base is on this line — even when newer releases were cut on it since; the change merges forward onto it. false only for a different, older line>,\"carries\":\"<what this line carries: for a line off the codeline's own base, the change made on the codeline's own line, ported in full: the story's whole change on the codeline's own line — what is already there and what this plan adds — every part of it, adapted where this line's code differs>\"}],\"consumers\":[{\"codeline\":\"<codeline>\",\"declaredRange\":\"<as its manifest declares it>\",\"receivesVia\":\"<the version, from the release lines above>\",\"usage\":[\"<file>: <how it reaches the code being changed>\"],\"update\":\"<the update that brings receivesVia into this consumer within its declared range — the lock file, or what its own update script does (read its scripts)>\",\"change\":\"<exactly none, or the change this consumer makes in its OWN code for this story — for example passing an option the provider adds — never none plus something to do or review>\"}]}]}\n</OVERALL_PLAN>\nRECEIVING THE PROVIDER'S RELEASE IS PART OF EVERY CONSUMER'S WORK in this story: a consumer that does not take the new version never gets the change. Name, for each consumer, the update that brings it in within the range it already declares (`update`) — its declared range itself is not changed. Where the consumer's own criteria need more than the new version — an option the provider adds, its own wording, its own call sites — that is its `change`. A consumer's `change` is code; a note that a file needs no edit is never written into that file.\nYour fix sites, after the plan, are files of THIS codeline only. Another codeline's files belong in the plan — its part and its usage — never among your fix sites.\nA story worked in ONE codeline writes the same plan: one entry under codelines, and packages empty unless that codeline provides one another codeline consumes.\n"
 }

package/orchestrations/prompts/templates/spec-shared-consumer.json

@@ -7,7 +7,8 @@
     "criteria left contradicted each other; the change reviewer rejected it on every attempt.",
     "Appended to the located fix sites only when a finding is shared, so every other story's prompt is",
     "unchanged.",
-    "Operator, 2026-10-06: a consumer's declared range is never changed by a story ('avoid package.json upgrades in this change'; a range may be locked for a reason); the provider ships the change on a release line inside each consumer's range."
+    "Operator, 2026-10-06: a consumer's declared range is never changed by a story ('avoid package.json upgrades in this change'; a range may be locked for a reason); the provider ships the change on a release line inside each consumer's range.",
+    "v3 (operator, 2026-10-22: \"If the plan agent is not given proper instructions to provide package updates then there is your rc\"): a consumer's plan names the update that brings in the provider's release, and any change of its own its criteria need — run 11's plan gave gotransit 'no change', it never received cx-shared 8.12.0, and its Writer looped."
   ],
   "description": "Composed into the spec agent's located fix sites when the detective reported a shared fix site: the shared facts, and how a codeline that consumes or provides a shared change is verified.",
   "id": "spec-shared-consumer",
@@ -15,6 +16,6 @@
   "placeholders": [
     "__SHARED_FACTS__"
   ],
-  "version": 2,
-  "body": "\nSHARED WITH ANOTHER CODELINE OF THIS STORY — the investigation reported:\n__SHARED_FACTS__\nHOW A SHARED CHANGE IS VERIFIED HERE. Where this codeline CONSUMES a package another codeline provides, its declared range is never part of this codeline's change: where the range does not take the version, the provider ships the change on a release line inside it, and this codeline receives it unedited. The dependency entry is not what this codeline's verification observes either: a criterion that reads the dependency entry, the lock file or what an install resolves describes HOW, not what a tester sees, and will be rejected. State each of this codeline's criteria as behaviour a tester observes through THIS codeline's own user-facing surface once it builds against the changed package from a release its declared range already takes — the place in this codeline that shows the shared behaviour now does what the story asks. Keep the description consistent with those criteria: never say this codeline's verification is limited to the dependency range, and never put out of scope the behaviour the criteria observe. Where this codeline PROVIDES the package, its criteria observe the behaviour through its own tests or its own surface. NEVER DECLARE ANOTHER CODELINE'S CHANGE out of scope, \"tracked separately\" or \"not needed\" unless the ticket itself says so: this story spans those codelines, and each of them is specified in its own right.\n"
+  "version": 3,
+  "body": "\nSHARED WITH ANOTHER CODELINE OF THIS STORY — the investigation reported:\n__SHARED_FACTS__\nHOW A SHARED CHANGE IS VERIFIED HERE. Where this codeline CONSUMES a package another codeline provides, its declared range is never part of this codeline's change: where the range does not take the version, the provider ships the change on a release line inside it, and this codeline receives it through the update its plan names. The dependency entry is not what this codeline's verification observes either: a criterion that reads the dependency entry, the lock file or what an install resolves describes HOW, not what a tester sees, and will be rejected. State each of this codeline's criteria as behaviour a tester observes through THIS codeline's own user-facing surface once it builds against the changed package from a release its declared range already takes — the place in this codeline that shows the shared behaviour now does what the story asks. Keep the description consistent with those criteria: never say this codeline's verification is limited to the dependency range, and never put out of scope the behaviour the criteria observe. Where this codeline PROVIDES the package, its criteria observe the behaviour through its own tests or its own surface. NEVER DECLARE ANOTHER CODELINE'S CHANGE out of scope, \"tracked separately\" or \"not needed\" unless the ticket itself says so: this story spans those codelines, and each of them is specified in its own right.\n"
 }

package/orchestrations/scripts/lib/producers/fix-plan.js

@@ -0,0 +1,327 @@
+/**
+ * THE CODE-GRAPH-DETECTIVE RENDERS ITS OWN ANSWER.
+ *
+ * KIND: fix-plan.  PRODUCER: code-graph-detective (see invocation-profiles.json).
+ *
+ * Before this file, the detective's answer became prompt text in two places, and the two had
+ * drifted in opposite directions:
+ *
+ *   claude.sh:2045           deliveryRole, runsIn, the UNVERIFIED and UNGROUNDED warnings, and
+ *                            the "nothing here produces the value" alarm
+ *   team-lead-review.sh:410  the changeRequired:false marker — which claude.sh never rendered
+ *
+ * So the writer was never told which sites were deliberately left alone, and the reviewer was
+ * never told that a prescribed helper does not exist. Each copy held a fact the other had lost.
+ * Nobody decided that; it is simply what two copies do — proven again on 2026-08-13, when
+ * deliveryRole was added to one renderer and the other never got it, within the hour.
+ *
+ * WHAT BELONGS HERE, AND WHAT DOES NOT
+ *
+ * Here: what the detective FOUND, in the detective's own terms, including how sure it is. It is
+ * the only actor that knows what its fields mean.
+ *
+ * Not here: what a reader should DO about it. "This is the plan of record, apply it" and "this is
+ * what the implementer was working from, judge the diff against it" are the same facts under two
+ * authorities, and the authority belongs to the consumer that declared the input. Bake one in and
+ * this module can only ever serve one consumer, which is where it came from.
+ */
+'use strict';
+
+const agentIo = require('../agent-io.js');
+
+/** The kind this producer publishes, and who it is published as. Declared once, read from here. */
+const KIND = 'fix-plan';
+const PRODUCER = 'code-graph-detective';
+
+/** false only when the producer actually SAID false. Absent is unknown, and unknown is not a defect. */
+function provenFalse(v) {
+  return v === false;
+}
+
+function renderSite(s) {
+  const file = s && s.file ? String(s.file) : '';
+  const fn = s && s.function ? String(s.function) : '';
+  const reason = s && s.reason != null ? String(s.reason) : '';
+
+  let line = `- **${file}**`;
+  if (fn !== '') line += ` (\`${fn}\`)`;
+
+  // A site the detective deliberately left alone. Without it a reader assumes an untouched file
+  // is an omission — the reviewer used to be the only one told, and it is the reviewer that would
+  // otherwise raise a finding about work that was correctly not done.
+  if (provenFalse(s.changeRequired)) {
+    line += '  [NO EDIT REQUIRED — part of the fix, correctly left unchanged]';
+  }
+
+  line += `: ${reason}`;
+
+  if (s.deliveryRole === 'produces') {
+    line += '  <== **THIS CHANGE PRODUCES THE VALUE** — it is what makes the new or corrected data'
+      + ' exist. Without it, every other change here only moves a value that never changed.';
+  } else if (s.deliveryRole === 'carries') {
+    line += '  (carries the value — moves or re-exposes what something else produced)';
+  } else if (s.deliveryRole === 'verifies') {
+    line += '  (verify only — no edit expected here)';
+  }
+
+  const runsIn = s.runsIn == null ? '' : String(s.runsIn);
+  if (runsIn !== '' && runsIn !== 'n/a') line += ` [runs: ${runsIn}]`;
+
+  if (s.shared && typeof s.shared === 'object') line += `\n  - **Shared:** ${sharedFact(s.shared)}`;
+
+  const fix = s.fix == null ? '' : String(s.fix);
+  if (fix !== '') {
+    line += `\n  - **Minimal fix:** ${fix}`;
+
+    // The helper named in the fix was not found in the repository. Live 2026-07-26 an answer of
+    // this shape sent a writer looking for a function that had never existed.
+    if (provenFalse(s.fixVerified)) {
+      line += ` ⚠️ UNVERIFIED: the helper named here (\`${s.helper || '?'}\`) was NOT found in the`
+        + ' repo — treat it as a HYPOTHESIS, not fact. Confirm it exists with the CodeGraph tool'
+        + ' before importing it; if it does not exist, do not invent it — solve the fix another'
+        + ' minimal way.';
+    }
+
+    // The quoted broken code is not in the file, so the diagnosis is about code that does not
+    // exist. Live 2026-07-26 exactly this prescribed halving a discount that is never applied,
+    // because the real defect was a key mismatch elsewhere.
+    if (provenFalse(s.evidenceVerified)) {
+      line += ` ⛔ UNGROUNDED DIAGNOSIS: the detective quoted \`${s.brokenLine || '?'}\` as the`
+        + ' broken code, but that expression is NOT in this file. The root cause below is'
+        + ' therefore a GUESS about code that does not exist — live 2026-07-26 an answer of'
+        + ' exactly this shape prescribed halving a discount that is in fact never applied at'
+        + ' all, because the real defect was a key mismatch elsewhere. Do NOT implement it as'
+        + ' written: re-derive the cause from the actual file contents first, and if the'
+        + ' prescribed change has no basis in the code you read, fix what IS broken instead.';
+    }
+  }
+
+  return line;
+}
+
+/** The detective's "shared" answer in its own terms: what, who provides it, and who receives it. */
+function sharedFact(sh) {
+  const consumers = (Array.isArray(sh.consumers) ? sh.consumers : []).map((c) => {
+    const range = c.declaredRange ? ` declares ${c.declaredRange}` : '';
+    const gets = c.receivesChange === true ? 'receives this change'
+      : c.receivesChange === false ? 'does NOT receive this change through that range'
+        : 'not known whether it receives this change';
+    return `${c.codeline}${range} — ${gets}`;
+  });
+  let out = `package \`${sh.package}\``;
+  if (sh.providedBy) out += `, provided by ${sh.providedBy}`;
+  if (sh.shipsInVersion) out += `, the change ships in version ${sh.shipsInVersion}`;
+  if (consumers.length) out += `; consumers: ${consumers.join('; ')}`;
+  if (sh.note) out += `. ${sh.note}`;
+  return out;
+}
+
+/**
+ * THE STORY'S OVERALL PLAN, as every agent of every codeline reads it — one rendering, so the detective of a
+ * later codeline, the spec agent, the writer and both reviewers are told the same plan (2026-10-06). The
+ * codeline being worked is marked, so each sees its own part within the whole.
+ */
+function overallPlanText(plan, here) {
+  if (!plan || !Array.isArray(plan.codelines) || !plan.codelines.length) return '';
+  const lines = ['THE OVERALL PLAN for this story — written once, for every codeline it is worked in:'];
+  const ordered = [...plan.codelines].sort((a, b) => (a.order == null ? 1e9 : a.order) - (b.order == null ? 1e9 : b.order));
+  for (const c of ordered) {
+    lines.push(`- ${c.order != null ? `${c.order}. ` : ''}${c.codeline}${c.codeline === here ? ' (THIS CODELINE)' : ''}: ${c.part}`);
+  }
+  for (const p of (Array.isArray(plan.packages) ? plan.packages : [])) {
+    lines.push(`Package \`${p.package}\`${p.providedBy ? `, provided by ${p.providedBy}` : ''}.`);
+    // THE LINE THIS PASS WORKS ON (lib/release-lines.sh sets it), so a line's agents know which branch they are on.
+    const _thisLine = process.env.EPAM_RELEASE_LINE || '';
+    for (const l of p.releaseLines || []) lines.push(`  release line ${l.line}: cut from ${l.base}, ships as ${l.version}${_thisLine && l.line === _thisLine ? ' (THIS RELEASE LINE — the one this pass works on)' : ''}${l.carries ? `; carries: ${l.carries}` : ''}`);
+    for (const c of p.consumers || []) {
+      lines.push(`  consumer ${c.codeline}${c.codeline === here ? ' (THIS CODELINE)' : ''}: declares ${c.declaredRange}, receives ${c.receivesVia}${c.update ? `; its update: ${c.update}` : ''}; its own change: ${c.change || 'none'}`);
+      for (const u of c.usage || []) lines.push(`    uses: ${u}`);
+    }
+  }
+  // WHO SETS THE VERSION (live run 3, 2026-10-07: told "ships as 8.12.0", the writer bumped package.json, and the lock
+  // file in a later attempt). The codeline's own release practice decides — read from its history, never assumed.
+  if ((Array.isArray(plan.packages) ? plan.packages : []).some((p) => (p.releaseLines || []).length)) {
+    lines.push('The version a release line ships as is set the way this codeline makes its releases — its history shows how; this story\'s change is the fix.');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * @param {Array|null|undefined} sites  the detective's fixSiteAnalysis, verbatim
+ * @returns {string} markdown, or '' when there is nothing to say
+ */
+function renderFixPlan(sites) {
+  const list = Array.isArray(sites) ? sites.filter((s) => s && typeof s === 'object') : [];
+  if (list.length === 0) return '';
+
+  let out = list.map(renderSite).join('\n');
+
+  // A plan in which every site only carries or verifies obtains nothing. Implementing it exactly
+  // yields code that runs, changes nothing anyone can see, and passes every check — which is how
+  // a story reaches its retry ceiling with a green diff. Only raised when the detective assigned
+  // roles at all: an older answer that was never asked the question is not accused of dodging it.
+  const roled = list.filter((s) => s.deliveryRole != null);
+  const producers = list.filter((s) => s.deliveryRole === 'produces');
+  if (producers.length === 0 && roled.length > 0) {
+    out += '\n\n⚠️ NONE OF THESE PRODUCE THE VALUE. Every site above only carries or verifies it —'
+      + ' they move, expose or re-render something that already exists. If this story needs a'
+      + ' value that does not exist yet, NO prescribed change obtains it, and implementing this'
+      + ' plan exactly will produce code that runs, changes nothing a user can see, and passes'
+      + ' every check. Find what must read, fetch, query or compute the new value, change that'
+      + ' too, and say so in your final message.';
+  }
+
+  return out;
+}
+
+/**
+ * The sites that belong to THIS story's codeline.
+ *
+ * Three codelines run as parallel lanes and each has its own answer. The canonical PRD's flat list
+ * is the UNION of all of them — on AMSD-2041, 13 sites where gotransit has 4, including three
+ * different prescriptions for one file naming five different env vars, two of them mutually
+ * exclusive designs. A writer handed three conflicting instructions for the same file picks one,
+ * and nothing makes it pick its own lane's.
+ *
+ * run-agent-orchestration.sh already scopes each lane's PRD this way; doing it here as well means
+ * publication is correct from EITHER PRD, rather than depending on which one a caller passes.
+ *
+ * An explicitly EMPTY entry is honoured: "this lane found nothing" is a real state and differs
+ * from "this lane has not run". A codeline ABSENT from the map falls back to the flat list —
+ * never to nothing, which would hand a writer an empty plan.
+ */
+function sitesFor(story) {
+  const per = story && story.fixSiteAnalysisPerCodeline;
+  const lane = story && story.codeline;
+  if (lane && per && Object.prototype.hasOwnProperty.call(per, lane)) return per[lane];
+  return story && story.fixSiteAnalysis;
+}
+
+/**
+ * A STORY'S PLAN: its own sites, and — when the detective reported a site SHARED between this
+ * story's codelines, in this lane or another — what is shared and where each sibling codeline's
+ * working copy is, RELATIVE to this codeline (detective-shared-package / fix-plan-shared). A story
+ * with nothing shared renders exactly renderFixPlan(sites).
+ */
+function renderStoryPlan(story, prd, sites) {
+  const own = sites === undefined ? sitesFor(story) : sites;
+  return renderFixPlan(own) + renderShared('fix-plan-shared', story, prd, own);
+}
+
+/**
+ * The shared section alone, under the template a consumer declares: what the detective reported as
+ * shared (this lane and its siblings) and where each sibling's working copy is, RELATIVE to this
+ * codeline. '' when nothing is shared. One gathering for the writer (fix-plan-shared) and the diff
+ * reviewers (review-shared), so the two can never be told different facts.
+ */
+function renderShared(templateId, story, prd, sites) {
+  const own = sites === undefined ? sitesFor(story) : sites;
+  const here = story && story.codeline;
+  const lanes = (story && Array.isArray(story.codelines)) ? story.codelines.filter(Boolean) : [];
+  const per = (story && story.fixSiteAnalysisPerCodeline) || {};
+  const shared = [];
+  for (const s of (Array.isArray(own) ? own : [])) {
+    if (s && s.shared && typeof s.shared === 'object') shared.push(`- ${here || 'this codeline'}: ${s.file} — ${sharedFact(s.shared)}`);
+  }
+  for (const cl of lanes.filter((c) => c !== here)) {
+    for (const s of (Array.isArray(per[cl]) ? per[cl] : [])) {
+      if (s && s.shared && typeof s.shared === 'object') shared.push(`- ${cl}: ${s.file} — ${sharedFact(s.shared)}`);
+    }
+  }
+  // THE STORY'S PLAN COMES FIRST, when there is one: it is what this codeline is worked from.
+  const plan = story && story.overallPlan ? overallPlanText(story.overallPlan, here) : '';
+  const port = releaseLinePort();
+  if (shared.length === 0 && !plan) return port;
+
+  const dirs = (prd && prd.project && Array.isArray(prd.project.outputDirs)) ? prd.project.outputDirs : [];
+  const dirOf = (cl) => (dirs.find((d) => d && d.codeline === cl) || {}).path;
+  const hereDir = dirOf(here) || (prd && prd.project && prd.project.outputDir);
+  const path = require('path');
+  const locations = lanes.filter((c) => c !== here).map((cl) => {
+    const there = dirOf(cl);
+    return there && hereDir ? `- ${cl}: ${path.relative(hereDir, there)}` : `- ${cl}: not recorded in this run's PRD`;
+  });
+  // eslint-disable-next-line global-require
+  const { renderEngineTemplate } = require('../engine-prompt.js');
+  return renderEngineTemplate(templateId, {
+    __SHARED_SITES__: [plan, ...shared].filter(Boolean).join('\n'),
+    __SIBLING_LOCATIONS__: locations.join('\n') || '- none recorded',
+  }) + port;
+}
+
+/**
+ * ON A RELEASE LINE, THE CHANGE IT PORTS: what the codeline's own line committed for this story, verbatim
+ * (lib/release-lines.sh writes it and names it in EPAM_MAIN_LINE_CHANGE). Part of renderShared, so the line's writer
+ * and its diff reviewers are given the same change to port and to compare against (AMSD-2974 run 9: both were given
+ * only the plan's summary, and a back-port carrying a fraction of the change was approved). '' off a release line,
+ * or when the own line committed nothing. A named change that cannot be read is an error, never an empty section.
+ */
+function releaseLinePort(env = process.env) {
+  const file = env.EPAM_MAIN_LINE_CHANGE || '';
+  const line = env.EPAM_RELEASE_LINE || '';
+  if (!file || !line) return '';
+  const change = require('fs').readFileSync(file, 'utf8');
+  if (!change.trim()) return '';
+  // eslint-disable-next-line global-require
+  const { renderEngineTemplate } = require('../engine-prompt.js');
+  return renderEngineTemplate('release-line-port', {
+    __RELEASE_LINE__: line,
+    __MAIN_LINE__: env.EPAM_MAIN_LINE_BRANCH || 'its own line',
+    __MAIN_LINE_CHANGE__: change.replace(/\n$/, ''),
+  });
+}
+
+/**
+ * Publish every story's plan, so consumers stop reading the detective's fields.
+ *
+ * A story with no sites publishes NOTHING, which clears any plan published earlier. That is the
+ * point rather than an optimisation: the detective re-runs, and a re-run that withdraws its
+ * findings must retract the plan too. Live 2026-08-13 a re-run degraded every site on three
+ * codelines and reported success — had the previous plan survived that, every consumer would have
+ * gone on acting on a plan the detective had taken back.
+ *
+ * @returns {number} how many stories now have a published plan
+ */
+function publishFixPlans(prd, env) {
+  const stories = (prd && Array.isArray(prd.stories)) ? prd.stories : [];
+  let published = 0;
+  for (const story of stories) {
+    if (!story || !story.id) continue;
+    const text = renderStoryPlan(story, prd);
+    agentIo.publish(PRODUCER, KIND, story.id, text, env);
+    if (text !== '') published += 1;
+  }
+  return published;
+}
+
+module.exports = {
+  overallPlanText, renderFixPlan, renderStoryPlan, renderShared, releaseLinePort, publishFixPlans, sharedFact, KIND, PRODUCER };
+
+// CLI: node fix-plan.js <prd.json> <story-id>   — emits the rendered plan on stdout.
+// The shell consumers call it this way; it is the same function either way, never a second copy.
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  try {
+    if (argv[0] === '--review-shared') {
+      // node fix-plan.js --review-shared <prd.json> <story-id> — the reviewers' shared section, or nothing.
+      const prd = JSON.parse(require('fs').readFileSync(argv[1], 'utf8'));
+      const story = (prd.stories || []).find((s) => s && s.id === argv[2]);
+      process.stdout.write(story ? renderShared('review-shared', story, prd) : '');
+    } else if (argv[0] === '--publish') {
+      // The orchestrator calls this after any step that can change the plan.
+      const prd = JSON.parse(require('fs').readFileSync(argv[1], 'utf8'));
+      const n = publishFixPlans(prd);
+      process.stderr.write(`[fix-plan] published for ${n} story(ies)\n`);
+    } else {
+      const [prdPath, storyId] = argv;
+      const prd = JSON.parse(require('fs').readFileSync(prdPath, 'utf8'));
+      const story = (prd.stories || []).find((s) => s && s.id === storyId);
+      process.stdout.write(story ? renderStoryPlan(story, prd, story.fixSiteAnalysis) : '');
+    }
+  } catch (e) {
+    // A rendering that cannot be produced must not look like a detective that found nothing:
+    // the caller sees a non-zero status and says so, rather than silently prompting without it.
+    process.stderr.write(`[fix-plan] ${(e && e.message) || e}\n`);
+    process.exit(1);
+  }
+}

package/orchestrations/scripts/spec-mode-runner.js

@@ -6627,7 +6627,9 @@ function parseOverallPlan(out) {
           ...(str(l.carries) ? { carries: str(l.carries) } : {}) })),
       consumers: (Array.isArray(p.consumers) ? p.consumers : []).filter((c) => c && typeof c.codeline === 'string')
         .map((c) => ({ codeline: c.codeline, declaredRange: str(c.declaredRange), receivesVia: str(c.receivesVia),
-          usage: (Array.isArray(c.usage) ? c.usage : []).filter((u) => typeof u === 'string'), change: str(c.change) })),
+          usage: (Array.isArray(c.usage) ? c.usage : []).filter((u) => typeof u === 'string'),
+          // the update that brings the provider's release into this consumer (detective-overall-plan v5; operator, 2026-10-22)
+          ...(str(c.update) ? { update: str(c.update) } : {}), change: str(c.change) })),
     }));
   return { codelines, packages };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amsd-pipeline-shared",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "description": "The AMSD pipeline's shared components, one source for the bash pipeline and its Claude workflows: the model-call gateway (llm-handler.sh — retry, ladder, self-heal, cost) and the libraries it runs.",
   "license": "UNLICENSED",
   "bin": {