amsd-pipeline-shared 0.5.11 → 0.5.13

package/orchestrations/prompts/templates/prd-model-coordinator.json

@@ -0,0 +1,24 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-16.",
+    "",
+    "Its role instructions were a command substitution piping profiles.json through python",
+    "inside the heredoc — a shell pipeline assembling the prompt, failing to an empty string in",
+    "silence, so the coordinator could run with no role at all and nothing would say so.",
+    "The permitted models and providers are placeholders, not prose: the persona named MiniMax-M3 outright, so on the claude stack the coordinator wrote a model no claude ladder declares into every story. A model off the ladder has no successor, so the writer could never escalate and the next run refused to start (2026-08-28)."
+  ],
+  "description": "Assigns models to stories from the PRD, under the project's own coordinator profile.",
+  "id": "prd-model-coordinator",
+  "seams": [
+    "prd-model-coordinator"
+  ],
+  "placeholders": [
+    "__PROFILE__",
+    "__MC_PRD_TARGET__",
+    "__MC_PHASE__",
+    "__MC_PERMITTED_MODELS__",
+    "__MC_PERMITTED_PROVIDERS__"
+  ],
+  "version": 1,
+  "body": "__PROFILE__\n\nPRD file: __MC_PRD_TARGET__\nPhase: __MC_PHASE__\n\nAssign model, aiProvider, and reasoningEffort to every pending story in this phase that is missing one or more of these fields. Write the updated PRD back to the file, then emit the JSON summary.\n\nPERMITTED MODELS — the only model names this run can route, in ladder order. The FIRST is the\nopening model: default to it when a story has no assignment.\n__MC_PERMITTED_MODELS__\n\nPERMITTED PROVIDERS — the only provider names this run can route:\n__MC_PERMITTED_PROVIDERS__\n"
+}

package/orchestrations/prompts/templates/previous-refusal.json

@@ -0,0 +1,15 @@
+{
+  "id": "previous-refusal",
+  "authority": "template",
+  "_what": "What an agent is told when its previous attempt was refused, and it must produce the artefact again.",
+  "_why": "This text was written in JavaScript at three call sites \u2014 the roster stage, the prompt generator and the roster namer \u2014 each with its own wording. Model-facing prose in engine code is unreviewable in the prompt layer, invisible to the drift checks that hold every project copy to its template, and unchangeable per project. It is a fragment: no seam declares it, so it renders from here and is composed into the prompt that needed it.",
+  "placeholders": [
+    "__ARTEFACT__",
+    "__REASON__"
+  ],
+  "body": "\n\n## Your previous attempt was REFUSED\n\n__REASON__\n\nProduce the __ARTEFACT__ again, correcting exactly this. Change nothing else: the rest of your previous attempt was accepted, and rewriting it invites a second refusal for a different reason.\n",
+  "mayBeEmpty": [
+    "__REASON__"
+  ],
+  "$whyMayBeEmpty": "Declared 2026-08-27 by sweeping the CLASS rather than the instance, after three runs died on it one placeholder at a time. Every call site for these writes an explicit empty branch \u2014 the story is not being split, attempt one carries no forced-retry note, no documentation was fetched, the persona prefix is optional \u2014 so absence is a real state, which is the renderer's own test. Placeholders supplied by a lookup that may FAIL (`x || ''`) are deliberately NOT here: for those, empty means broken, and declaring them would hide the blank-brief defect the renderer exists to surface. Unanimity is required \u2014 one deliberate branch among several defensive lookups is not a licence."
+}

package/orchestrations/prompts/templates/profile-augmentor.json

@@ -0,0 +1,24 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-16.",
+    "",
+    "Decides whether a confirmed finding warrants an addendum to an agent profile. The role to",
+    "target is supplied explicitly -- \"target THIS profile, not a guess from the gate name\" --",
+    "because the gate that reported a finding is not the agent that caused it, and augmenting",
+    "the wrong profile teaches the wrong agent."
+  ],
+  "description": "Judges whether a confirmed finding is a novel pattern worth appending to an agent profile.",
+  "id": "profile-augmentor",
+  "seams": [
+    "prd-change-reviewer"
+  ],
+  "placeholders": [
+    "__PROFILE__",
+    "__FINDING_JSON__",
+    "__PROFILES_FILE__",
+    "__STORY_ID__",
+    "__STORY_AGENT_ROLE__"
+  ],
+  "version": 1,
+  "body": "__PROFILE__\n\n## Finding to evaluate\n```json\n__FINDING_JSON__\n```\n\nProfiles file: __PROFILES_FILE__\nStory that wrote the offending code: __STORY_ID__\nThat story's agentRole (target THIS profile, not a guess from the gate name): __STORY_AGENT_ROLE__\n\nCheck if the pattern is novel and append a rule if needed. Write the updated profiles.json back, then emit the JSON summary."
+}

package/orchestrations/prompts/templates/project-prompt-generation.json

@@ -0,0 +1,54 @@
+{
+  "$why": [
+    "Authored 2026-08-15. Nothing generated project prompts before this: the seven project",
+    "copies in existence were minted by hand, so a new project had no way to get its own.",
+    "",
+    "BOOTSTRAP, so COPIED and never generated — it cannot be its own output.",
+    "",
+    "The placeholder rule is stated as the one unbreakable rule because prompt-library renders",
+    "strictly in both directions. A generated prompt that drops, renames or invents a single",
+    "placeholder does not degrade; it throws mid-run at whichever seam needed it. The output is",
+    "also checked mechanically by lib/project-prompt-contract.js — the prompt asks, the contract",
+    "enforces, because asking a model nicely is not a guarantee.",
+    "",
+    "2026-08-15, found by a rehearsal project on its first end-to-end run: __TEMPLATE_BODY__ was wrapped in a",
+    "code fence, and templates that contain fences of their own (repro-test-writer, code-graph-",
+    "detective) were truncated at their FIRST closing fence. The generated prompt then dropped",
+    "every placeholder past that point and the contract refused it, three attempts running. An",
+    "explicit BEGIN/END marker cannot collide with the content it delimits.",
+    "",
+    "Reclassified 2026-08-16. This was marked engine-internal, on the reasoning that the engine",
+    "renders it rather than an agent. That was wrong once the prompt-builder became a seam of its",
+    "own: the agent that runs on this prompt IS an agent, with a ladder, a budget and read access",
+    "to the template zone. Its prompt belongs to its seam like every other.",
+    "",
+    "2026-08-17: this template had NO layer field, and absent defaults to \"engine\" — so the provisioning filter dropped it and the builder then failed with \"'project-prompt-generation' is not installed. It must be declared in bootstrap.copyVerbatim\" while bootstrap DID declare it. It was declared and then filtered out.",
+    "",
+    "It is project-layer by construction: project-prompt-builder.js reads the PROJECT copy of this template (outDir) to generate every other project prompt — \"the generator's own prompt comes from the project copy just installed, not from an engine-side string\". The layer field now states what the code does.",
+    "2026-10-06, AMSD-2974: metrolinx's repro-test-writer was generated as \"write a spec file for a Toast component at cx-shared\" — the generator completed sentences its slots complete at run time, using the one ticket it was shown, and the reviewer passed it because every claim was true. The prompt serves every story and call; a slot's place is the pipeline's; narrowing and a displaced slot are findings."
+  ],
+  "body": "You are specialising ONE generic agent prompt for ONE specific project. You are the same agent that just minted this project's roles, so you already know what this project is and who will work on it.\n\n## The template you must specialise\n\nIts id is __GEN_TEMPLATE_ID__ and its purpose is: __GEN_TEMPLATE_DESCRIPTION__\n\nEverything between the two markers below is the template, verbatim. The markers are not\npart of it. A code fence cannot delimit this: several templates contain fences of their\nown, so the first closing fence would truncate the body mid-instruction.\n\n-----BEGIN TEMPLATE BODY-----\n__GEN_TEMPLATE_BODY__\n-----END TEMPLATE BODY-----\n\n## What this project is\n\n__GEN_PROJECT_CONTEXT__\n\nCodelines in scope and their declared dependencies:\n__GEN_CODELINE_CONTEXT__\n\nThe roles you minted for this project:\n__GEN_MINTED_ROLES__\n\n## The one rule you cannot break\n\nYou are given the template as numbered SEGMENTS — the prose that sits BETWEEN its placeholders. You\nnever see the placeholders and you must never write one. The pipeline puts them back between your\nsegments, in their original positions, after you answer.\n\n- Return EXACTLY as many segments as you were given, in the same order.\n- Specialise the WORDING of each segment for this project. A segment may be reworded freely.\n- NEVER write a placeholder token (the SCREAMING_SNAKE form between double underscores). It would be substituted a second time, or read as literal\n  text to the agent. The pipeline owns them; you own the prose.\n- An empty segment is legitimate — some segments are only the join between two adjacent slots.\n\nThis is why the rule is shaped this way: when the generator was asked to reproduce placeholders\ncharacter-for-character while rewriting the prose around them, it lost them. On 2026-09-08 that\nproduced 25 refusals in one run and aborted it at 37 of 39 prompts. You cannot drop a token you\nwere never given.\n\nFor context, the placeholders the pipeline will restore are: __GEN_TEMPLATE_PLACEHOLDERS__\n\n## The prompt serves every story and every call\n\nThis prompt is reused for every story and every call this project makes to the agent — not only for the ticket in scope now. Where one segment ends and the next begins, the pipeline inserts a value that changes with every call: the role for this turn, the file to write, the command to run, the diff, the story. A segment that ends mid-sentence is completed at run time by that value. Never complete it yourself, never move words across a segment break, and never write a value the pipeline supplies. Never make the ticket in scope, one story's component or one story's file the subject of the prompt: the tickets are named above only so you know what kind of work this project does.\n\n## The other rule you cannot break\n\nThe template's OUTPUT SHAPE is a contract too. Every field name the template states in its response\nformat is read by a consumer that will reject an answer without it — the agent would produce work\nnothing accepts, and the seam fails after the model has already been paid for.\n\n- Reproduce every field name EXACTLY, in the same shape the template states it.\n- NEVER drop one because it looks redundant, and NEVER rename one to something clearer.\n- NEVER add a field. A consumer reads by name and has no place to put an invention.\n\nThe output fields this template states are exactly: __GEN_TEMPLATE_OUTPUT_FIELDS__\n\n## Before you answer\n\nCheck your reply against both lists above: every output field must appear in what you are about to\nsend, and no placeholder token may. A specialisation that drops a field is refused and the work is\nredone, so the check costs you nothing and the omission costs an attempt.\n\n## What specialising means\n\nKeep the template's instructions, its output format, its prohibitions and its reasoning intact. They encode failures this pipeline has already paid for. You are not rewriting the prompt or improving its wording.\n\nAdd only what a competent engineer joining THIS project would need and could not infer from the generic text:\n- the conventions, layout and idioms this codebase actually uses\n- the commands this project runs to build, test and type-check\n- the traps this stack presents that a generic prompt would not warn about\n\nGround every addition in the project context above. If the context does not tell you something, say nothing about it — an invented convention is worse than a missing one, because the agent will follow it.\n\nDo not name a file, symbol, package or command that does not appear in the context you were given.\n\n## How to answer\n\nReturn the SEGMENT blocks back, in the same shape and order you were shown: one marker line per\nsegment, each followed by your wording for that segment, and close with the END SEGMENTS marker.\n\nPlain text between the markers. No JSON, no escaping, no markdown fences. A segment may be empty.\nNo placeholder tokens anywhere — the pipeline restores them between your segments.\n\n(The marker lines are not reproduced here on purpose: the only ones in this prompt are the real\nsegments you must answer, so there is never a second set to confuse them with.)\n__GEN_PREVIOUS_REFUSAL__\n\n# Do not invent a path\n\nEvery specific path, filename, directory or symbol you write will be checked against the\nrepository by a reviewer. A plausible-looking path you reasoned your way to — `src/routes/...`,\n`src/pages/api/...` — is the most common reason a generated prompt is rejected and regenerated,\nand each regeneration risks dropping the placeholders above.\n\nSo: state a specific path ONLY when it appears in the facts or the codeline block you were given\nabove — and never a path that belongs to one story's change: that reaches the agent at run time. You were handed those precisely so you would not have to guess.\n\nWhen you have no verified path for something, say the general thing instead — \"the checkout form\ncomponent\", \"the API route that handles checkout\" — which is true, useful to the agent, and cannot\nbe falsified. A prompt that is accurate and general survives review; one that is specific and\ninvented does not.\n\nNever guess a path to sound concrete.\n",
+  "description": "Specialise one generic agent prompt for one project, preserving its placeholder contract.",
+  "id": "project-prompt-generation",
+  "placeholders": [
+    "__GEN_CODELINE_CONTEXT__",
+    "__GEN_MINTED_ROLES__",
+    "__GEN_PREVIOUS_REFUSAL__",
+    "__GEN_PROJECT_CONTEXT__",
+    "__GEN_TEMPLATE_BODY__",
+    "__GEN_TEMPLATE_DESCRIPTION__",
+    "__GEN_TEMPLATE_ID__",
+    "__GEN_TEMPLATE_OUTPUT_FIELDS__",
+    "__GEN_TEMPLATE_PLACEHOLDERS__"
+  ],
+  "version": 3,
+  "seams": [
+    "prompt-builder"
+  ],
+  "layer": "project",
+  "mayBeEmpty": [
+    "__PREVIOUS_REFUSAL__"
+  ],
+  "$whyOutputFields": "Added 2026-08-27. Placeholders had a section of their own, three hard rules and an injected list; output fields had one clause in the middle of a sentence and no list. The failures matched that asymmetry exactly — in run 20260827T125654Z six generations dropped placeholders and one dropped seven output fields at once. Judging an agent against a contract it was never shown is the defect; the list is derived from the template by the same function the contract check uses, so the two cannot disagree.",
+  "$whyGenPrefix": "The generator's OWN placeholders are namespaced __GEN_*, because it embeds another template's body inside its prompt and then substitutes values across the whole string. Three of its names were also names templates use — __PROJECT_CONTEXT__, __CODELINE_CONTEXT__, __PREVIOUS_REFUSAL__ in roster-specialisation, __CODELINE_CONTEXT__ in project-roster-review, __TEMPLATE_BODY__ in prompt-review — so the embedded template's own placeholders were replaced with real project text and the agent was then refused for 'dropping' tokens that were never in its input. Substituting the body LAST stopped the corruption; it did not stop the model seeing one name used two ways. A reserved prefix removes the collision by construction, so no future template can reintroduce it."
+}

package/orchestrations/prompts/templates/project-roster-review.json

@@ -0,0 +1,11 @@
+{
+  "id": "project-roster-review",
+  "authority": "template",
+  "_what": "Falsifies a project roster against the canonical roster it was derived from.",
+  "_why": "A reviewer given only the derived roster can judge plausibility. Checking that an ancestor is genuinely close, that inherited structure was not quietly changed, and that a claim about the codeline is true, needs the source and the code.",
+  "placeholders": [
+    "__CODELINE_CONTEXT__",
+    "__PAIR_BLOCK__"
+  ],
+  "body": "A project roster has been derived from the canonical roster. Your job is to FALSIFY it, not to admire it.\n\nThe codelines it claims to be specialised for:\n__CODELINE_CONTEXT__\n\nTHE ENTRIES UNDER REVIEW ARE BELOW, canonical text and derived text side by side. You are given\nthem directly because a roster is far too large to read through tools in one pass — that is what\nmade an earlier review answer that there was nothing to review. Judge what is here. This is a\nBATCH: other entries are judged in their own passes, so never report that agents are missing.\n\n__PAIR_BLOCK__\n\nUse your tools for one thing only: checking whether a claim a derived persona makes about a\ncodeline is actually true. You have the source and the code; a judgement you could have made without opening either is not a review.\n\n## What makes a roster defective\n\nA RULE WAS WEAKENED. The derived persona may change what an agent KNOWS. It may not change what an agent is REQUIRED TO DO. If the canonical persona forbids something, demands evidence for a finding, or names a check that must pass, and the derived one softens or drops it, that is a blocking defect. Compare the two texts; do not rely on the derived one reading sensibly on its own.\n\nA CLAIM ABOUT THE CODELINE IS FALSE. A persona asserting a framework, a directory, a helper or a command that is not there is worse than a generic sentence, because the agent will act on it and the next reader cannot tell which claims were verified. Check the ones you can; report the ones you checked.\n\nAN ANCESTOR IS NOT CLOSE. Every entry names a canonical ancestor and inherits its ladder, its tool grant and its output contract from it. An entry whose work is nothing like its ancestor’s has inherited a budget and a set of tools that do not fit the job.\n\nAN AGENT LOST ITS PURPOSE. Specialisation replaces what an agent knows, never what it is for. A derived persona that has become a different agent means the pipeline will invoke it for the original work.\n\n## What is NOT a defect\n\nContent that differs from canonical. That is the point of the exercise, and difference alone is never a finding.\n\nA persona that is shorter, plainer, or omits a generic aside that does not apply to this codeline.\n\nAn agent you judge irrelevant to this project. You cannot know which seams a run will reach, and the roster must cover every canonical agent.\n\n## Evidence\n\nEvery finding names the agent, states which of the four defects it is, and quotes what you read — the canonical line and the derived line, or the path you opened and what was there. A finding without that is discarded before anyone sees it, so an unsupported one costs you the finding.\n\nReturn no findings if you find none. An empty finding list from a review that RAN is the correct answer for a sound roster.\n\nTHE VERDICT AND THE FINDINGS MUST AGREE. If you answer 'defects_found' you must list what you found — a verdict condemning the roster while naming nothing cannot be acted on or argued with, and it is discarded as a review that did not substantiate itself. If nothing you checked failed, the honest answer is 'sound' with no findings; that is a real result, not a weaker one.\n"
+}

package/orchestrations/prompts/templates/prompt-claim-adjudication.json

@@ -0,0 +1,21 @@
+{
+  "$why": [
+    "AMSD-2974 runs 3 and 4 (2026-10-09) died in the Agents Phase after the prompt reviewer struck project prompts five times.",
+    "A reviewer is a model; on wording it is strict, and a correct prompt can lose every attempt to a strike that does not hold.",
+    "When the reviewer strikes the SAME claim a second time, this agent — on a different rung — settles that one claim against",
+    "the repositories. A claim that holds is withdrawn from the verdict; one that does not stands. No claim is settled by rule."
+  ],
+  "id": "prompt-claim-adjudication",
+  "version": 1,
+  "description": "Settles one disputed claim in a generated project prompt against the repositories, when the reviewer has struck it twice.",
+  "placeholders": [
+    "__CLAIM__",
+    "__CODELINE_BLOCK__",
+    "__FINDING__",
+    "__TOOL_LINE__"
+  ],
+  "seams": [
+    "prompt-claim-adjudicator"
+  ],
+  "body": "You settle ONE disputed claim about a software project. A generated project prompt states it; a reviewer has struck it twice as false; the prompt's author kept it. Neither side wins by repetition. You decide from the repositories.\n\nTHE CLAIM, as the prompt states it:\n__CLAIM__\n\nWHAT THE REVIEWER SAYS IT FOUND:\n__FINDING__\n\nTHE CODELINES OF THIS PROJECT (you may read all of them):\n__CODELINE_BLOCK__\n\n__TOOL_LINE__\n\n# How to decide\n\n1. Open the repositories and check the claim yourself. Do not take the reviewer's finding, or the claim, on trust.\n2. Read the claim as an engineer working in this repository would read it. It HOLDS when what it points at is real and\n   is what it says it is: the file, directory, component, dependency, range, command or behaviour exists as stated.\n3. Loose wording that still points at something real HOLDS — a component referred to by the name of the folder that\n   holds it (\"the Foo component\" for Foo/Bar.tsx), a path missing intermediate directories, a file named without its\n   directory. Whether something is \"a folder\" or \"a component\" is wording; whether it EXISTS and is what the claim\n   says it is, is the question. It does NOT hold when the thing it names is\n   absent, when a version, range, command or behaviour differs from what the repository says, or when it attributes\n   something to the wrong file or codeline.\n4. A name may be a DIRECTORY. A file glob does not match directories; list the parent directory before you call\n   anything absent.\n5. Cite what you opened: the path and line, or the command and what it returned.\n\nAnswer with ONLY this block:\n\n<ADJUDICATION>\n{\"holds\": true|false, \"evidence\": \"<what you opened and what it showed>\"}\n</ADJUDICATION>\n"
+}

package/orchestrations/prompts/templates/prompt-review.json

@@ -0,0 +1,48 @@
+{
+  "$why": [
+    "Created 2026-08-17.",
+    "",
+    "A generated project prompt was checked ONLY against its template's placeholder contract:",
+    "non-empty body, no dropped placeholders, no invented ones. That proves the derivative is",
+    "WIREABLE. It proves nothing about whether what it says about the project is TRUE.",
+    "",
+    "So a prompt could tell a writer that this codeline's tests live in a directory it does not",
+    "have, that a dependency is present when it is not, or that a file owns behaviour it does not",
+    "— and it would install cleanly, because every placeholder was in the right place. The agent",
+    "then inherits that claim as instruction, and the pipeline has no later step that questions it.",
+    "",
+    "The roster gets exactly this treatment already: roster-review reads the repositories and",
+    "falsifies the claims in a generated brief before any implementer inherits them. Thirty-three",
+    "generated prompts got none. This is that reviewer, pointed at prompts.",
+    "",
+    "SCOPE IS DELIBERATELY NARROW. It judges CLAIMS ABOUT THE PROJECT, not prompt quality, not",
+    "wording, not whether the specialisation was ambitious enough. A reviewer invited to improve",
+    "prose rewrites prompts that were correct, and the placeholder contract already covers",
+    "structure. Only a claim that can be checked against the repository is in scope.",
+    "2026-10-06, AMSD-2974: metrolinx's repro-test-writer was generated as \"write a spec file for a Toast component at cx-shared\" — the generator completed sentences its slots complete at run time, using the one ticket it was shown, and the reviewer passed it because every claim was true. The prompt serves every story and call; a slot's place is the pipeline's; narrowing and a displaced slot are findings."
+  ],
+  "description": "Falsifies what a generated project prompt claims about this project, before any agent inherits it.",
+  "seams": [
+    "prompt-review"
+  ],
+  "consumer": "engine",
+  "id": "prompt-review",
+  "version": 3,
+  "body": "You are reviewing a PROJECT PROMPT that was generated by specialising a generic template for this specific project. Another agent will receive it as its system prompt and act on every claim in it.\n\nTHE GENERIC TEMPLATE IT WAS DERIVED FROM:\n__TEMPLATE_BODY__\n\nTHE GENERATED PROJECT PROMPT UNDER REVIEW (id: __PROMPT_ID__):\n__GENERATED_BODY__\n\nTHE CODELINES THIS PROJECT WORKS ON, and what each one declares:\n__CODELINE_BLOCK__\n\nTHE WORK THE PROJECT WAS ASKED TO DO:\n__TICKET_BLOCK__\n\n__TOOL_LINE__\n\n# What is in scope\n\nTWO QUESTIONS ONLY:\n1. Does the generated prompt state anything about this project that is FALSE?\n2. Is the generated prompt NARROWED TO ONE STORY OR CALL, or does a slot NO LONGER FIT ITS SENTENCE? (See \"A prompt narrowed to one call\" below.)\n\nA claim is in scope when it can be checked against a repository — a path, a file, a directory, a dependency, a command, a framework, a convention, a symbol, an ownership statement ('X owns Y'). Open the codelines and check it.\n\nExamples of a finding:\n- it names a test directory, file suffix or framework this codeline does not use\n- it names a dependency, script or command the manifest does not declare\n- it asserts a file, module or symbol exists that does not\n- it attributes behaviour to a file that does not contain it\n- it describes a codeline this project does not have, or confuses two that it does\n- it instructs the agent to run something this codeline cannot run\n\n# A prompt narrowed to one call\n\nThe generated prompt is not written for the ticket in scope now. It is reused for every story and every call this project makes to the agent, and each call's specifics — the role for the turn, the file to write, the command to run, the diff, the story — arrive through the slots (the SCREAMING_SNAKE tokens between double underscores) at run time. Compare it with the template, slot by slot, and report as a finding:\n- a statement true only for one story or one call — this ticket's component, a file or path one story will write, a command aimed at one story's file — written where the template leaves that to a slot. It is a finding even when it is true today: the next story receives it as an instruction.\n- a slot that no longer fits its sentence: in the template the slot completes or sits inside a sentence; in the generated prompt the words around it were moved, completed by hand, or rewritten, so the run-time value would land in the wrong place or be said twice. Quote the template's words around that slot and the generated prompt's.\nFor these findings `claim` quotes the generated text, `checked` names the template slot you compared it with, and `found` says what the template has there. Give no `verification` field: this is read from the two texts, not from the repository.\n\n# Before you call anything absent: SEARCH for it\n\nA path in a generated prompt is frequently ABBREVIATED rather than wrong. Looking at the literal\nstring, finding nothing there, and reporting a false claim is the single most common way this\nreview does damage — it rejects a prompt that was RIGHT about the project, the generator rewrites\nthe whole thing to escape a finding that was not real, and in rewriting it drops the placeholders\nthe pipeline depends on. Three attempts of that aborts the run.\n\nSo, for every path, file, directory or symbol the prompt names:\n\n1. SEARCH the codeline for it by BASENAME before concluding it does not exist. `src/routes/checkouts/[checkoutId].ts`\n   and `src/pages/api/checkouts/[checkoutId].ts` are both a SHORTENED form of\n   `src/pages/api/v1/ecommerce/checkouts/[checkoutId].ts`, which exists — that is a near-miss path,\n   NOT a false claim, and it is not a finding.\n2. An IMPRECISE path that RESOLVES to a real file is not a finding. Neither is a partial path, a\n   path missing intermediate directories, or a file named without its directory.\n   A NAME MAY BE A DIRECTORY. A file glob such as **/Name* matches files, not directories, and a\n   text search matches contents, not folder names — neither can show you a directory. Before you\n   call a component, module or folder absent, list its parent directory and look for it there.\n3. Report it ONLY when the thing genuinely does not exist anywhere in the codeline — no file of\n   that name, no such dependency in the manifest, no such symbol in the sources.\n\nAbsence at one exact path is not absence from the repository. If you did not search, you do not\nknow, and \"I did not find it where the prompt said\" is not a finding you may report.\n\n# What is NOT in scope\n\nDo not review wording, tone, length, structure or ambition. Do not propose improvements. Do not object that the prompt is too close to, or too far from, the template — how far it may diverge is decided elsewhere, and the placeholder contract is already enforced mechanically. (A prompt narrowed to one call, or a slot that no longer fits its sentence, is not a question of distance — report it as above.)\n\nA prompt that says nothing false and serves every call is SOUND, however plain it is.\n\n# Evidence\n\nReturn every defect you can evidence, and nothing you cannot. For each finding, say what you CHECKED and what you FOUND, naming the file or manifest you read. A finding without a check is an opinion, and an opinion about a prompt is not a defect.\n\nWhere a finding turns on whether a named path or dependency is present, fill in the verification field as well as the prose. The pipeline re-runs that exact check against the repository and DISCARDS any finding the check refutes — so a careless reading costs nothing, and a correct one is confirmed independently of how convincingly you argued it.\n\nIf every claim checks out, return no findings. An empty finding list from a review that RAN is the correct answer for a sound prompt.\n\n# How to return the verdict\n\nEmit the verdict INLINE as the last thing you write, wrapped in these exact tags. Do not write it\nto a file, and do not use a tool to deliver it — a verdict delivered any other way is not read, and\nthe prompt is then installed unreviewed.\n\n<PROMPT_REVIEW>\n{\"falseClaims\": []}\n</PROMPT_REVIEW>\n\n`falseClaims` is a list of the defects you evidenced. Each entry is an object:\n\n- `claim`       — the false statement, quoted from the generated prompt\n- `checked`     — what you opened or ran to test it, naming the file or manifest\n- `found`       — what was actually there\n- `verification` — when the finding turns on a named path or dependency being present or absent,\n                  an object stating what to re-check, so the pipeline can confirm it independently\n\nTHE ROLES THIS PROJECT MINTED, which is the ground truth for any claim naming an agent:\n\n__ROSTER_BLOCK__\n\nA prompt naming one of these is stating a FACT, not inventing one. Check the list before calling a\nrole false — an unverifiable claim is not a false claim, and rejecting one costs a regeneration and\nteaches the generator nothing.\n\nTHE BLOCK IS THE WHOLE ANSWER. Nothing you write outside it is read — the consumer matches the\ntags and discards everything else. Do not narrate your investigation, do not summarise what you\nchecked, and do not restate the prompt back. Put your evidence INSIDE `checked` and `found` on the\nfinding it belongs to, where it is kept; anywhere else it is thrown away.\n\nMeasured 2026-08-27: reviews averaged 3,366 output tokens to deliver a 13-token verdict. Every one\nof those tokens was billed and 99% of them were discarded unread.\n\nAn empty list is the correct verdict for a sound prompt. Emit the block either way: the block is\nhow a review that RAN is distinguished from one that did not run at all.\n",
+  "placeholders": [
+    "__CODELINE_BLOCK__",
+    "__GENERATED_BODY__",
+    "__PROMPT_ID__",
+    "__ROSTER_BLOCK__",
+    "__TEMPLATE_BODY__",
+    "__TICKET_BLOCK__",
+    "__TOOL_LINE__"
+  ],
+  "mayBeEmpty": [
+    "__PROMPT_ID__"
+  ],
+  "$whyMayBeEmpty": "Declared 2026-08-27 by sweeping the CLASS rather than the instance, after three runs died on it one placeholder at a time. Every call site for these writes an explicit empty branch — the story is not being split, attempt one carries no forced-retry note, no documentation was fetched, the persona prefix is optional — so absence is a real state, which is the renderer's own test. Placeholders supplied by a lookup that may FAIL (`x || ''`) are deliberately NOT here: for those, empty means broken, and declaring them would hide the blank-brief defect the renderer exists to surface. Unanimity is required — one deliberate branch among several defensive lookups is not a licence.",
+  "$whyPersonaMayBeEmpty": "The reviewer's own brief is optional and the supplier says so in as many words — 'Absent is fine — the template's persona section is then simply empty'. The template did not declare it, so the renderer refused, and reviewPrompt caught the refusal and installed the prompt UNREVIEWED. profiles.json carries no 'prompt-review' persona at all, so that happened on EVERY prompt: turning the review on would have reviewed nothing while looking enabled. Found 2026-08-27 by running the reviewer live against a prompt containing a deliberate false claim.",
+  "$whyTerse": "The parser reads only <PROMPT_REVIEW>...</PROMPT_REVIEW>. Prose around it is billed and discarded, and at 3,366 output tokens per call for a 13-token verdict it was the single largest line in the run's bill after prompt generation itself.",
+  "$whyRosterBlock": "Added 2026-08-27. The reviewer received the generated prompt, the template, the codelines and the tickets — and NOT the roster. So a prompt that correctly named fare-rules-engineer, mocka-detective, schedule-display-engineer and mockb-detective was rejected twice as false: the reviewer had no list to check against and refused what it could not verify. Each false rejection forced a regeneration and often a rung escalation, so the missing input was billed repeatedly. Identical defect to roster-review being asked to falsify a claim about pipeline stages it was never shown."
+}

package/orchestrations/prompts/templates/qa-brownfield-scope.json

@@ -0,0 +1,36 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-16. The brownfield addendum every QA",
+    "gate prompt receives.",
+    "",
+    "These gates were designed for a freshly-scaffolded application. Pointed at 850+ existing",
+    "files and a three-line change, only TWO of six mentioned the code the run had changed",
+    "(2026-07-26): sast spent its budget on 70 pre-existing dependency CVEs, review-ranger",
+    "returned a 211-byte pass without naming the diff, perf-sentinel was handed browser E2E",
+    "context for a backend string comparison, and fuzz-weaver returned nothing at all.",
+    "",
+    "Two corrections: judge THIS CHANGE, and be allowed to say the change is not your business.",
+    "Silence is indistinguishable from failure and a fabricated pass is worse than both, so",
+    "not_applicable is a first-class verdict with a required reason.",
+    "",
+    "The file list arrived as a shell default-expansion whose fallback sentence was itself",
+    "prompt text. The caller supplies the whole value now, fallback included: prompt wording",
+    "hidden inside ${VAR:-...} is wording nobody reviews."
+  ],
+  "description": "The brownfield scope addendum appended to every QA gate prompt.",
+  "id": "qa-brownfield-scope",
+  "seams": [
+    "qa-gate:sast",
+    "qa-gate:spec-validator",
+    "qa-gate:review-ranger",
+    "qa-gate:mutant-hunter",
+    "qa-gate:fuzz-weaver",
+    "qa-gate:perf-sentinel"
+  ],
+  "placeholders": [
+    "__GATE__",
+    "__FILES__"
+  ],
+  "version": 1,
+  "body": "\n## BROWNFIELD — judge THIS CHANGE, not the codebase\nThis is an existing production repository. It contains problems that predate this\nrun and are none of this run's business. You are reviewing one small change to it.\n\nFiles this run produced or modified:\n__FILES__\n\nRULES:\n1. Findings MUST be about the lines this run changed. A pre-existing issue in an\n   untouched file, or on an untouched line of a touched file, is NOT a finding\n   here — reporting it blocks a correct change over somebody else's problem.\n2. If __GATE__ has nothing meaningful to say about a change of this kind, return\n   verdict \"not_applicable\" with a one-line reason. That is a valid, useful\n   answer. Do NOT invent a finding to look thorough, and do NOT return \"pass\" to\n   mean \"I could not evaluate this\".\n3. Prefer fewer, real findings over broad coverage."
+}

package/orchestrations/prompts/templates/qa-evidence-labels.json

@@ -0,0 +1,28 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-16.",
+    "",
+    "The headings that label precomputed evidence for the review-ranger and mutant-hunter gates, and the truncation notice that goes with a source file longer than the window. That notice is prompt text of the most consequential kind: it is the only thing telling an agent that what it is judging is incomplete."
+  ],
+  "description": "Headings that label precomputed evidence for the QA gates, and the notice shown when a file is truncated.",
+  "seams": [
+    "qa-gate:review-ranger",
+    "qa-gate:mutant-hunter"
+  ],
+  "id": "qa-evidence-labels",
+  "version": 2,
+  "bodies": {
+    "review_diff": "Files changed:\n__DIFF_STAT__\n\nTypeScript diff (first 300 lines):\n__DIFF_PATCH__",
+    "mutant_oracle": "Changed source files:\n__SRC_CONTENT__\n\nExisting test files (first 60 lines each):\n__TEST_CONTENT__",
+    "truncation_notice_source": "\n[PARTIAL VIEW — __MUT_SRC_TOTAL_LINES__ total lines. The window above is centred on the lines THIS PHASE changed and states its own range. Do not assume the omitted remainder is unmutated.]",
+    "truncation_notice_test": "\n[PARTIAL VIEW — __MUT_TEST_TOTAL_LINES__ total lines. The window above is centred on the lines THIS PHASE changed and states its own range. Do not assume the omitted remainder has no assertions.]"
+  },
+  "placeholders": [
+    "__DIFF_PATCH__",
+    "__DIFF_STAT__",
+    "__SRC_CONTENT__",
+    "__TEST_CONTENT__",
+    "__MUT_SRC_TOTAL_LINES__",
+    "__MUT_TEST_TOTAL_LINES__"
+  ]
+}

package/orchestrations/prompts/templates/qa-fuzz-weaver.json

@@ -0,0 +1,35 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-15. One of the six QA sentinels",
+    "(11-16 of 20), each a separate gate with its own verdict.",
+    "",
+    "All six embed a shared scope block through a command substitution rather than a plain",
+    "variable, so it arrives as a value like any other. They are six templates and not one",
+    "parameterised template: they instruct differently, and a single prompt with six branches",
+    "would hide which instructions a given gate actually received.",
+    "",
+    "2026-08-17: asked for \"a vitest test skeleton\". On any other stack the agent produced a test the codeline cannot run — the executableTest field exists precisely so the finding can be verified by execution.",
+    "",
+    "2026-08-17: named vitest twice — once as the framework to write a skeleton in, once as the runner not to invoke. The instruction is framework-independent; naming one told every non-Node agent to produce a test its codeline cannot run."
+  ],
+  "body": "You are acting as the fuzz-weaver agent.\n__GATE_SCOPE__\n\nPhase: __PHASE_ID__\nProject root: __PROJECT_ROOT__\nE2E routing override context:\n- FORCE_LIGHTPANDA=__FORCE_LIGHTPANDA__\n- FORCE_PLAYWRIGHT=__FORCE_PLAYWRIGHT__\n- routingDecision=__ROUTING_DECISION__\n\nPerform property-based / fuzz testing analysis on changed files in this phase.\nUse git diff to identify changed source files, then for each public function:\n1. Derive input domains from TypeScript parameter types\n2. Propose fuzz test cases with fast-check style property definitions\n3. Assess whether existing tests cover each edge case\n\nFocus on: config parsing, provider request construction, billing calculations,\ntool input validation (path traversal, shell metacharacters), auth token parsing.\n\nFor any case with status=\"vulnerability\", you MAY include an optional\n\"executableTest\" field: a test skeleton in this codeline's own framework (its tests run with: __TEST_COMMAND__) (as a single string) showing\nthe import path and the assertion that SHOULD pass if the code is correct —\ne.g. `import { parseAdults } from '../src/server'; expect(parseAdults('0')).toBeNull()`.\nIMPORTANT: Do NOT run or execute any tests. Do NOT use Bash to run\nany test runner. Write the test structure only — it will be reviewed by a\nhuman. A vulnerability claim is valid without an executableTest; do not spend\ntime executing code to verify findings.\n\nOutput format (strict JSON, no markdown fences, no preamble — emit directly as your final message, do NOT write to a file):\n{\n  \"agent\": \"fuzz-weaver\",\n  \"phase\": \"__PHASE_ID__\",\n  \"summary\": { \"functionsAnalysed\": N, \"fuzzCasesProposed\": N, \"covered\": N, \"gaps\": N, \"vulnerabilities\": N },\n  \"cases\": [{ \"function\": \"...\", \"file\": \"...\", \"line\": N, \"property\": \"...\", \"generator\": \"...\", \"invariant\": \"...\", \"status\": \"covered|gap|vulnerability\", \"recommendation\": \"...\", \"executableTest\": \"...(only when status=vulnerability)...\" }],\n  \"verdict\": \"pass|warn|fail\"\n}",
+  "description": "Instructions for the fuzz-weaver QA gate.",
+  "id": "qa-fuzz-weaver",
+  "placeholders": [
+    "__FORCE_LIGHTPANDA__",
+    "__FORCE_PLAYWRIGHT__",
+    "__GATE_SCOPE__",
+    "__PHASE_ID__",
+    "__PROJECT_ROOT__",
+    "__ROUTING_DECISION__",
+    "__TEST_COMMAND__"
+  ],
+  "version": 1,
+  "seams": [
+    "qa-gate:fuzz-weaver"
+  ],
+  "mayBeEmpty": [
+    "__GATE_SCOPE__"
+  ],
+  "$whyGateScopeMayBeEmpty": "__GATE_SCOPE__ is the brownfield addendum (_brownfield_gate_scope in run-agent-orchestration.sh) and is empty on greenfield by design — 'whose flow is deliberately unchanged'. Undeclared, every QA gate refused to render on a greenfield phase and the testing gates failed with no instructions (£0 greenfield harness, 2026-09-13)."
+}

package/orchestrations/prompts/templates/qa-mutant-hunter.json

@@ -0,0 +1,28 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-15. One of the six QA sentinels",
+    "(11-16 of 20), each a separate gate with its own verdict.",
+    "",
+    "All six embed a shared scope block through a command substitution rather than a plain",
+    "variable, so it arrives as a value like any other. They are six templates and not one",
+    "parameterised template: they instruct differently, and a single prompt with six branches",
+    "would hide which instructions a given gate actually received."
+  ],
+  "body": "You are acting as the mutant-hunter agent.\n\nPhase: __PHASE_ID__\nProject root: __PROJECT_ROOT__\n\nIMPORTANT: All evidence has been pre-computed and is injected below. Do NOT attempt to call any shell commands, bash, or tools. Analyze ONLY the injected source and test file data.\n__GATE_SCOPE__\n\n## Source and Test Evidence (hard evidence — treat as ground truth)\n__MUTANT_ORACLE_SUMMARY__\n\nAnalyze the pre-computed source and test code above. For each changed source file:\n1. Propose mutations: operator swaps, comparison inversions, boolean negations,\n   early returns, boundary shifts, removed null checks, swapped arguments\n2. For each mutation, determine if the existing tests shown above would catch it\n3. Focus on critical paths: provider failover, tool safety, auth, billing, agent state\n\nIf no source changes are detected or evidence is insufficient, output \"verdict\": \"warn\" with mutationScore of 100 and 0 mutations (non-blocking — nothing to test).\n\nOutput format (strict JSON, no markdown fences, no preamble):\n{\n  \"agent\": \"mutant-hunter\",\n  \"phase\": \"__PHASE_ID__\",\n  \"summary\": { \"mutationsProposed\": N, \"killed\": N, \"survived\": N, \"noCoverage\": N, \"mutationScore\": 75 },\n  \"mutations\": [{ \"file\": \"...\", \"line\": N, \"originalCode\": \"<the EXACT line(s) from the file being mutated, copied verbatim — required for any status:survived mutation, or it will be treated as unverified>\", \"mutatedCode\": \"...\", \"status\": \"killed|survived|no-coverage\", \"relatedTest\": \"...\", \"recommendation\": \"...\" }],\n  \"verdict\": \"pass|warn|fail\"\n}\nThe summary.survived count MUST equal the number of status:survived entries in the mutations array — they describe the same thing and must agree.",
+  "description": "Instructions for the mutant-hunter QA gate.",
+  "id": "qa-mutant-hunter",
+  "placeholders": [
+    "__GATE_SCOPE__",
+    "__MUTANT_ORACLE_SUMMARY__",
+    "__PHASE_ID__",
+    "__PROJECT_ROOT__"
+  ],
+  "version": 1,
+  "seams": [
+    "qa-gate:mutant-hunter"
+  ],
+  "mayBeEmpty": [
+    "__GATE_SCOPE__"
+  ],
+  "$whyGateScopeMayBeEmpty": "__GATE_SCOPE__ is the brownfield addendum (_brownfield_gate_scope in run-agent-orchestration.sh) and is empty on greenfield by design — 'whose flow is deliberately unchanged'. Undeclared, every QA gate refused to render on a greenfield phase and the testing gates failed with no instructions (£0 greenfield harness, 2026-09-13)."
+}

package/orchestrations/prompts/templates/qa-oracle-evidence.json

@@ -0,0 +1,35 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-16.",
+    "",
+    "The ORACLE HEADINGS: each prepends a block of precomputed evidence to a gate prompt and tells",
+    "the gate how to treat it — \"hard evidence, treat as ground truth\". That framing is the whole",
+    "point of precomputing it. Without it a gate re-derives what it was already given, which is the",
+    "max-iteration exhaustion these oracles exist to prevent.",
+    "",
+    "One body per oracle, because each names its own source and a gate is handed only its own.",
+    "",
+    "2026-08-17: the section heading named npm. It is rendered above whatever dependency evidence the codeline produced, which is not always npm audit."
+  ],
+  "description": "Prepends precomputed oracle evidence to a QA gate prompt and frames it as ground truth.",
+  "seams": [
+    "qa-gate:sast",
+    "qa-gate:spec-validator"
+  ],
+  "id": "qa-oracle-evidence",
+  "version": 1,
+  "bodies": {
+    "semgrep": "## Semgrep Static Analysis Results (hard evidence — treat as ground truth)\n__SEMGREP_SUMMARY__\n\n__SAST_PROMPT__",
+    "npm_audit": "## Dependency Audit Results (hard evidence — dependency CVEs)\n__AUDIT_SUMMARY__\n\n__SAST_PROMPT__",
+    "typescript": "## TypeScript Compiler Results (hard evidence — treat as ground truth)\n__TSC_SUMMARY__\n\n__SAST_PROMPT__",
+    "test_results": "## Actual Test Results (hard evidence — use this as ground truth)\n__ORACLE_SUMMARY__\n\n__SPEC_PROMPT__"
+  },
+  "placeholders": [
+    "__SEMGREP_SUMMARY__",
+    "__SAST_PROMPT__",
+    "__AUDIT_SUMMARY__",
+    "__TSC_SUMMARY__",
+    "__ORACLE_SUMMARY__",
+    "__SPEC_PROMPT__"
+  ]
+}

package/orchestrations/prompts/templates/qa-perf-sentinel.json

@@ -0,0 +1,30 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-15. One of the six QA sentinels",
+    "(11-16 of 20), each a separate gate with its own verdict.",
+    "",
+    "All six embed a shared scope block through a command substitution rather than a plain",
+    "variable, so it arrives as a value like any other. They are six templates and not one",
+    "parameterised template: they instruct differently, and a single prompt with six branches",
+    "would hide which instructions a given gate actually received."
+  ],
+  "body": "You are acting as the perf-sentinel agent.\n__GATE_SCOPE__\n\nPhase: __PHASE_ID__\nProject root: __PROJECT_ROOT__\nE2E routing override context:\n- FORCE_LIGHTPANDA=__FORCE_LIGHTPANDA__\n- FORCE_PLAYWRIGHT=__FORCE_PLAYWRIGHT__\n- routingDecision=__ROUTING_DECISION__\n\nPerform performance analysis on files changed in this phase.\nUse git diff to identify changed source files, then analyse:\n1. Algorithmic complexity (flag O(n²)+ on unbounded inputs)\n2. Memory allocation hotspots (object creation in loops, unbounded caches)\n3. Async performance (sequential awaits → Promise.all, missing timeouts, stream backpressure)\n4. Startup time impact (heavy imports, sync I/O at module load)\n5. Provider-specific (unnecessary Message[] copies, redundant token counting)\n\nOutput format (strict JSON, no markdown fences, no preamble — emit directly as your final message, do NOT write to a file):\n{\n  \"agent\": \"perf-sentinel\",\n  \"phase\": \"__PHASE_ID__\",\n  \"summary\": { \"filesAnalysed\": N, \"findingsCount\": N, \"blockerCount\": N, \"estimatedStartupImpactMs\": N },\n  \"findings\": [{ \"severity\": \"blocker|major|minor\", \"category\": \"complexity|memory|async|startup|provider\", \"file\": \"...\", \"line\": N, \"codeSnippet\": \"<the EXACT line(s) from the file that show the problem, copied verbatim — required for any blocker-severity finding, or it will be treated as unverified>\", \"description\": \"...\", \"estimatedImpact\": \"high|medium|low\", \"suggestedFix\": \"...\" }],\n  \"verdict\": \"pass|warn|fail\"\n}",
+  "description": "Instructions for the perf-sentinel QA gate.",
+  "id": "qa-perf-sentinel",
+  "placeholders": [
+    "__FORCE_LIGHTPANDA__",
+    "__FORCE_PLAYWRIGHT__",
+    "__GATE_SCOPE__",
+    "__PHASE_ID__",
+    "__PROJECT_ROOT__",
+    "__ROUTING_DECISION__"
+  ],
+  "version": 1,
+  "seams": [
+    "qa-gate:perf-sentinel"
+  ],
+  "mayBeEmpty": [
+    "__GATE_SCOPE__"
+  ],
+  "$whyGateScopeMayBeEmpty": "__GATE_SCOPE__ is the brownfield addendum (_brownfield_gate_scope in run-agent-orchestration.sh) and is empty on greenfield by design — 'whose flow is deliberately unchanged'. Undeclared, every QA gate refused to render on a greenfield phase and the testing gates failed with no instructions (£0 greenfield harness, 2026-09-13)."
+}

package/orchestrations/prompts/templates/qa-review-ranger.json

@@ -0,0 +1,28 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-15. One of the six QA sentinels",
+    "(11-16 of 20), each a separate gate with its own verdict.",
+    "",
+    "All six embed a shared scope block through a command substitution rather than a plain",
+    "variable, so it arrives as a value like any other. They are six templates and not one",
+    "parameterised template: they instruct differently, and a single prompt with six branches",
+    "would hide which instructions a given gate actually received."
+  ],
+  "body": "You are acting as the review-ranger agent.\n\nPhase: __PHASE_ID__\nProject root: __PROJECT_ROOT__\n\nIMPORTANT: All evidence has been pre-computed and is injected below. Do NOT attempt to call any shell commands, bash, or tools. Analyze ONLY the injected git diff data.\n__GATE_SCOPE__\n\n## Git Diff Evidence (hard evidence — treat as ground truth)\n__REVIEW_DIFF_SUMMARY__\n\nAnalyze the pre-computed diff above and produce a structured JSON report covering:\n1. Complexity hotspots (cyclomatic complexity > 10, nesting > 4)\n2. Code duplication (near-identical blocks > 5 lines)\n3. API contract drift (exported signature changes without test updates)\n4. Error handling completeness (swallowed errors in critical paths)\n5. Test coverage gaps (new public functions without tests)\n6. Naming consistency (camelCase vars, PascalCase types, UPPER_SNAKE constants)\n\nIf the injected evidence is insufficient to determine a verdict with confidence, output \"verdict\": \"pass\" with 0 findings rather than fabricating a failure.\n\nOutput format (strict JSON, no markdown fences, no preamble):\n{\n  \"agent\": \"review-ranger\",\n  \"phase\": \"__PHASE_ID__\",\n  \"summary\": { \"filesReviewed\": N, \"findingsCount\": N, \"blockerCount\": N, \"majorCount\": N, \"minorCount\": N },\n  \"findings\": [{ \"severity\": \"blocker|major|minor\", \"category\": \"...\", \"file\": \"...\", \"line\": N, \"codeSnippet\": \"<the EXACT line(s) from the file that show the problem, copied verbatim — required for any blocker-severity finding, or it will be treated as unverified>\", \"description\": \"...\", \"suggestedFix\": \"...\" }],\n  \"verdict\": \"pass|fail\"\n}",
+  "description": "Instructions for the review-ranger QA gate.",
+  "id": "qa-review-ranger",
+  "placeholders": [
+    "__GATE_SCOPE__",
+    "__PHASE_ID__",
+    "__PROJECT_ROOT__",
+    "__REVIEW_DIFF_SUMMARY__"
+  ],
+  "version": 1,
+  "seams": [
+    "qa-gate:review-ranger"
+  ],
+  "mayBeEmpty": [
+    "__GATE_SCOPE__"
+  ],
+  "$whyGateScopeMayBeEmpty": "__GATE_SCOPE__ is the brownfield addendum (_brownfield_gate_scope in run-agent-orchestration.sh) and is empty on greenfield by design — 'whose flow is deliberately unchanged'. Undeclared, every QA gate refused to render on a greenfield phase and the testing gates failed with no instructions (£0 greenfield harness, 2026-09-13)."
+}

package/orchestrations/prompts/templates/qa-sast-sentinel.json

@@ -0,0 +1,35 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-15. One of the six QA sentinels",
+    "(11-16 of 20), each a separate gate with its own verdict.",
+    "",
+    "All six embed a shared scope block through a command substitution rather than a plain",
+    "variable, so it arrives as a value like any other. They are six templates and not one",
+    "parameterised template: they instruct differently, and a single prompt with six branches",
+    "would hide which instructions a given gate actually received.",
+    "",
+    "2026-08-17: named package.json, its devDependencies/dependencies section names, and six Node tools as examples. The dev-vs-runtime distinction is the real rule and it survives — but the EVIDENCE already carries that classification per package (lib/handlers/dependency-audit-summary.py tags each runtime/dev/transitive), so the prompt points at the tag instead of teaching the agent to read one ecosystem's manifest.",
+    "",
+    "2026-08-17: named npm audit and the TypeScript compiler as the evidence sources. The evidence is injected either way; naming one ecosystem's tools told the agent to expect data a Rust or Python codeline never produces.",
+    "",
+    "2026-08-17: named npm audit as the evidence source. The evidence is injected either way and already carries a runtime/dev/transitive tag per package.",
+    "2026-08-19: the `rule` field was free-form, and the brownfield-CVE gate matched a prefix nothing required the model to emit. The vocabulary now comes from config/sast-vocabulary.json, which the gate reads too."
+  ],
+  "body": "You are acting as the sast-sentinel agent.\n\nPhase: __PHASE_ID__\nProject root: __PROJECT_ROOT__\n\nIMPORTANT: All evidence has been pre-computed and is injected above. Do NOT attempt to call any shell commands, bash, or tools. Analyze ONLY the injected static-analysis, dependency-audit and compiler evidence below.\n__GATE_SCOPE__\n\nAnalyze the pre-computed evidence above and produce a structured JSON report covering:\n\n1. TypeScript compiler diagnostics: Results are pre-injected as '## TypeScript Compiler Results'. Each 'error TS' line is a finding with severity 'major'.\n\n2. Security pattern scan: Based on the Semgrep results injected above, classify findings:\n   - ERROR/WARNING severity Semgrep findings → severity 'major' or 'blocker'\n   - INFO severity findings → severity 'minor'\n   - Patterns to flag if Semgrep missed them (text scan only, no tool calls):\n     command injection, path traversal, hardcoded secrets, unsafe eval\n\n3. Dependency CVE classification (from the injected dependency-audit evidence):\n   - NAME every dependency-CVE finding with a `rule` that begins `__DEPENDENCY_CVE_RULE_PREFIX__`, followed by the severity and the scope — for example `__DEPENDENCY_CVE_RULE_PREFIX__critical-runtime`, `__DEPENDENCY_CVE_RULE_PREFIX__high-runtime`, `__DEPENDENCY_CVE_RULE_PREFIX__dev-only`. The pipeline identifies dependency findings by that prefix; a finding named any other way is treated as a finding about the code itself and is NOT eligible to be reported as pre-existing repository debt.\n   - CVEs in RUNTIME dependencies (the evidence tags these (runtime)) → severity 'blocker' if critical, 'major' if high\n   - CVEs in DEV-ONLY dependencies (the evidence tags these (dev)) → severity 'minor' regardless of CVSS score. Dev tools never run in production and their CVEs do not affect application security.\n   - NEVER classify a dev-dependency CVE as 'blocker' or 'major'.\n\nIf the injected evidence is insufficient to determine a verdict with confidence, output \"verdict\": \"pass\" with 0 findings rather than fabricating a failure.\n\nOutput format (strict JSON, no markdown fences, no preamble):\n{\n  \"agent\": \"sast-sentinel\",\n  \"phase\": \"__PHASE_ID__\",\n  \"summary\": { \"filesScanned\": N, \"findingsCount\": N, \"blockerCount\": N },\n  \"findings\": [{ \"severity\": \"blocker|major|minor\", \"rule\": \"...\", \"file\": \"...\", \"line\": N, \"description\": \"...\", \"suggestedFix\": \"...\" }],\n  \"verdict\": \"pass|fail\"\n}",
+  "description": "Instructions for the sast-sentinel QA gate.",
+  "id": "qa-sast-sentinel",
+  "placeholders": [
+    "__GATE_SCOPE__",
+    "__PHASE_ID__",
+    "__PROJECT_ROOT__",
+    "__DEPENDENCY_CVE_RULE_PREFIX__"
+  ],
+  "version": 1,
+  "seams": [
+    "qa-gate:sast"
+  ],
+  "mayBeEmpty": [
+    "__GATE_SCOPE__"
+  ],
+  "$whyGateScopeMayBeEmpty": "__GATE_SCOPE__ is the brownfield addendum (_brownfield_gate_scope in run-agent-orchestration.sh) and is empty on greenfield by design — 'whose flow is deliberately unchanged'. Undeclared, every QA gate refused to render on a greenfield phase and the testing gates failed with no instructions (£0 greenfield harness, 2026-09-13)."
+}

package/orchestrations/prompts/templates/qa-spec-validator.json

@@ -0,0 +1,30 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-15. One of the six QA sentinels",
+    "(11-16 of 20), each a separate gate with its own verdict.",
+    "",
+    "All six embed a shared scope block through a command substitution rather than a plain",
+    "variable, so it arrives as a value like any other. They are six templates and not one",
+    "parameterised template: they instruct differently, and a single prompt with six branches",
+    "would hide which instructions a given gate actually received."
+  ],
+  "body": "You are acting as the spec-validator agent.\n__GATE_SCOPE__\n\nPhase: __PHASE_ID__\nProject root: __PROJECT_ROOT__\nE2E routing override context:\n- FORCE_LIGHTPANDA=__FORCE_LIGHTPANDA__\n- FORCE_PLAYWRIGHT=__FORCE_PLAYWRIGHT__\n- routingDecision=__ROUTING_DECISION__\n\nIMPORTANT: All evidence has been pre-injected below. Do NOT call any tools, ReadFile, or Bash commands. Classify each AC using ONLY the injected story oracle, test oracle, and implementation evidence.\n\nFor each story in the phase:\n1. Use the pre-injected criteria from the Story Oracle section — it states which\\n   kind the story is judged against. If it records none, you cannot report\\n   compliance against an empty set: say so, do not pass.\n2. Use the pre-injected git diff and file excerpts as implementation evidence\n3. Classify each criterion as: met, partial, unmet, or untestable\n   - untestable: evidence is insufficient to determine status — do NOT call tools to investigate further\n\nOutput format (strict JSON, no markdown fences, no preamble — emit directly as your final message, do NOT write to a file):\n{\n  \"agent\": \"spec-validator\",\n  \"phase\": \"__PHASE_ID__\",\n  \"stories\": [{\n    \"storyId\": \"...\",\n    \"title\": \"...\",\n    \"criteria\": [{ \"text\": \"...\", \"status\": \"met|partial|unmet|untestable\", \"evidence\": \"...\", \"gaps\": \"...\" }],\n    \"overallCompliance\": 85,\n    \"verdict\": \"pass|warn|fail\"\n  }],\n  \"overallVerdict\": \"pass|warn|fail\"\n}",
+  "description": "Instructions for the spec-validator QA gate.",
+  "id": "qa-spec-validator",
+  "placeholders": [
+    "__FORCE_LIGHTPANDA__",
+    "__FORCE_PLAYWRIGHT__",
+    "__GATE_SCOPE__",
+    "__PHASE_ID__",
+    "__PROJECT_ROOT__",
+    "__ROUTING_DECISION__"
+  ],
+  "version": 1,
+  "seams": [
+    "qa-gate:spec-validator"
+  ],
+  "mayBeEmpty": [
+    "__GATE_SCOPE__"
+  ],
+  "$whyGateScopeMayBeEmpty": "__GATE_SCOPE__ is the brownfield addendum (_brownfield_gate_scope in run-agent-orchestration.sh) and is empty on greenfield by design — 'whose flow is deliberately unchanged'. Undeclared, every QA gate refused to render on a greenfield phase and the testing gates failed with no instructions (£0 greenfield harness, 2026-09-13)."
+}

package/orchestrations/prompts/templates/release-line-port.json

@@ -0,0 +1,22 @@
+{
+  "$why": [
+    "AMSD-2974 run 9, 2026-10-13: the 8.x change grew in its own review and self-heal (header-measured placement,",
+    "pointer-events on the empty container, the close click not propagating); the 7.x back-port's writer and reviewer",
+    "were given only the plan's one-line summary of what the line carries, written before any code existed. The",
+    "back-port carried a fraction of the change and its reviewer approved it, because nothing put the two lines' code",
+    "side by side. Operator: 'to have two shared changes with different code and reviewer passed without comparing",
+    "two code lines is insane.' Rendered by the fix-plan producer, for the writer and the diff reviewers alike, only",
+    "on a release-line pass whose codeline's own line has a committed change.",
+    "2026-10-13 live harness round 2: the reviewer saw the 7.x line was 'materially weaker than the already-approved main-line fix', called it major because the line's root-cause analysis named fewer fixes, and approved. What was written before the change existed does not narrow it."
+  ],
+  "description": "Appended to a release line's plan, for its writer and its diff reviewers: the change the codeline's own line committed for this story, verbatim, and what porting it means.",
+  "id": "release-line-port",
+  "seams": [],
+  "placeholders": [
+    "__RELEASE_LINE__",
+    "__MAIN_LINE__",
+    "__MAIN_LINE_CHANGE__"
+  ],
+  "version": 2,
+  "body": "\n\nTHE CHANGE THIS RELEASE LINE PORTS. This pass works release line __RELEASE_LINE__. The same story was changed, reviewed and approved on this codeline's own line (__MAIN_LINE__); this is that change exactly as committed there:\n```diff\n__MAIN_LINE_CHANGE__\n```\nThe change on this release line is that change, ported: every hunk above is present here, or adapted where this line's source differs — and each adaptation names the difference in this line's source that requires it. What the change above delivers — what a user sees and can do, and what its tests assert — is delivered on this line too. Everything else this line was given — the plan's summary of what it carries, the root-cause analysis, the fix sites and what they mark as needing no edit — was written before the change above existed; where any of it prescribes less than the change above, the change above is what ships on this line. When writing: port it hunk by hunk with its tests, and say in your final message, per hunk, ported or adapted (and why). When reviewing: put this line's diff beside the change above, hunk by hunk. A hunk missing or weakened with no reason in this line's source is a BLOCKER finding — not major, whatever the plan or the root-cause analysis prescribes — and a line carrying one is not approved.\n"
+}