amsd-pipeline-shared 0.5.11 → 0.5.13

package/orchestrations/prompts/templates/repro-feedback.json

@@ -0,0 +1,31 @@
+{
+  "$why": [
+    "Moved out of brownfield-repro-test-writer.sh on 2026-08-16.",
+    "",
+    "What the repro-writer is told when its previous attempt failed, in the two ways it can: the test did not COMPILE, or it compiled and its assertions failed against a fix that is already committed. The second is the harder message to get right -- a failing assertion there means the TEST is wrong, not the code, and a writer told otherwise will 'fix' working code.",
+    "",
+    "The compiler errors arrived through a grep | head -8 pipeline inside the prompt -- a truncation of the very errors the writer is told to eliminate, so error nine onward were invisible and the rewrite could never be complete. The caller supplies them.",
+    "",
+    "And the failure JSON arrived head -c 1200 -- cut at a byte offset, mid-structure, so what the writer was shown of its own failure was not valid JSON at all.",
+    "",
+    "A third way the previous attempt can fail, added 2026-09-11: the test compiled and passed and the CLIENT REPOSITORY refused to commit it. Live on AMSD-1919, lint-staged rejected one `export` (jest/no-export); the test stayed uncommitted, the repro gate blocked, and the whole story was re-implemented. The hook output is the rejection reason, quoted verbatim — the engine knows no hook rule."
+  ],
+  "description": "Feedback to the repro-writer when its previous test failed to compile or failed its assertions.",
+  "seams": [
+    "repro-test-writer"
+  ],
+  "id": "repro-feedback",
+  "version": 1,
+  "bodies": {
+    "typecheck": "\n\n## COMPILER ERRORS FROM YOUR PREVIOUS ATTEMPT — FIX THESE\nYour last test ran but did NOT compile. tsc reported, for this exact file:\n```\n__COMPILER_ERRORS__\n```\nRewrite the file so these are gone. Mock objects must satisfy the full type.",
+    "assertions": "\n\n## YOUR TEST FAILED AGAINST THE FIX THAT IS ALREADY COMMITTED\nThe change for this story is ALREADY in the working tree. Your test ran but __FAILED__ of __TOTAL__ assertion(s) FAILED, which means your test contradicts the implemented change.\nRead the diff above again and assert the behaviour it ACTUALLY produces.\n```\n__FAILURE_JSON__\n```",
+    "commitRejected": "\n\n## THE REPOSITORY REJECTED YOUR PREVIOUS TEST AT COMMIT — FIX WHAT IT NAMES\nYour last test compiled and passed, and the repository refused to commit it. Its own commit hook reported:\n```\n__HOOK_OUTPUT__\n```\nThe file is still in place. Change ONLY what the hook names, keep every assertion, and write it again to the same path."
+  },
+  "placeholders": [
+    "__FAILED__",
+    "__TOTAL__",
+    "__COMPILER_ERRORS__",
+    "__FAILURE_JSON__",
+    "__HOOK_OUTPUT__"
+  ]
+}

package/orchestrations/prompts/templates/repro-role.json

@@ -0,0 +1,32 @@
+{
+  "$why": [
+    "Moved out of brownfield-repro-test-writer.sh on 2026-08-16.",
+    "",
+    "Two roles, one per story kind: a test that proves an ALREADY-committed change, or a test that reproduces a bug a fix has already addressed. One body each -- the two say different things about whether the code under test is expected to pass, and conflating them produces a test written against the wrong expectation.",
+    "",
+    "2026-08-16: the PROOF REQUIREMENT and the DIFF HEADING moved here too.",
+    "",
+    "Both were string literals in brownfield-repro-test-writer.sh, assigned to _req_proof and",
+    "_diff_heading and injected into this same prompt as __REQ_PROOF__ / __DIFF_HEADING__. So the",
+    "role sentence lived in the template while the sentence that actually decides whether the test is",
+    "acceptable — 'it must FAIL against the pre-fix code and PASS with the fix' — lived in a shell",
+    "script, where no prompt review reaches it and it could not be diffed against the role it pairs",
+    "with. They vary together on exactly the same condition (story kind), so they belong in the same",
+    "file, keyed the same way."
+  ],
+  "description": "What kind of test the repro-writer is being asked for, by story kind.",
+  "seams": [
+    "repro-test-writer"
+  ],
+  "id": "repro-role",
+  "version": 1,
+  "bodies": {
+    "proves_committed_change": "write ONE test that proves a change which has ALREADY been implemented and committed",
+    "reproduces_fixed_bug": "write ONE bug-reproducing test for a fix that has ALREADY been implemented and committed",
+    "proof_proves_committed_change": "3. The test MUST prove the verification criteria above against the committed change. Assert the observable outcome the change now produces — not the mechanism, and not that some prior behaviour was broken. This is a NEW capability: there is no pre-fix failure to reproduce, and a test written as though there were will be rejected. It MUST PASS with the change in place.",
+    "proof_reproduces_fixed_bug": "3. The test MUST genuinely REPRODUCE the bug: it must FAIL against the pre-fix code and PASS with the fix. Assert the corrected observable value — a test that passes regardless of the fix is worthless and will be rejected.",
+    "heading_proves_committed_change": "The change that was just made (diff vs baseline)",
+    "heading_reproduces_fixed_bug": "The fix that was just made (diff vs baseline)"
+  },
+  "placeholders": []
+}

package/orchestrations/prompts/templates/repro-test-writer.json

@@ -0,0 +1,55 @@
+{
+  "id": "repro-test-writer",
+  "layer": "project",
+  "version": 3,
+  "description": "The dedicated test-writer turn. The implementer is forbidden to write tests; this agent owns them.",
+  "$why": [
+    "Extracted verbatim from a heredoc in brownfield-repro-test-writer.sh on 2026-08-13 — one of",
+    "the 34 prompts embedded in scripts. Prompt prose in a shell string is live code: a quote ends",
+    "the string and a backtick executes. It also cannot be reviewed, diffed or corrected without",
+    "editing the engine.",
+    "",
+    "The template is NEVER executed. A project-authority copy is what runs; self-heal is the only",
+    "process permitted to mutate it.",
+    "",
+    "2026-08-13: the heading already said \"assert the OBSERVABLE outcome\" and a test still asserted SDK configuration flags. Saying it abstractly was not enough, so the prohibition is concrete and names the shapes that do not count.",
+    "",
+    "2026-08-15: the mock-verification block was added after run 20260815T142007Z, in which this",
+    "agent mocked a transport module the SDK under test never calls. The mock intercepted nothing,",
+    "the real path ran, three of its own assertions failed, suiteState latched red and Step 3.55",
+    "failed a run whose implementation was sound (tsc clean, 1200/1203 passing).",
+    "",
+    "The asymmetry that allowed it: code-graph-detective was already forbidden to name an unproven",
+    "third-party symbol and was given resolve-package-symbol.sh to prove it with. This agent names",
+    "third-party modules constantly - that is what mocking is - and had neither the rule nor the",
+    "tool. One agent was held to evidence; the other was trusted to remember.",
+    "",
+    "2026-08-20: this told the agent to run `_run_project_verification` — a shell FUNCTION defined in claude.sh:5398. The agent's bash tool is a separate subprocess where engine functions do not exist, so the command failed to stderr, `2>&1 | grep <target>` matched nothing, and the agent saw EMPTY OUTPUT. From its own trace: \"Good — no output means no typecheck errors for our file.\" \"If that prints anything, FIX YOUR FILE\" could never print anything; the instruction was unfalsifiable, and the warning it carries — \"blocks the whole pipeline five steps later\" — is exactly what happened.",
+    "",
+    "The command now comes from what the PROJECT declares (.epam/verification.json, read by verification-plugin's detectVerification). A codeline declaring no typecheck is told so rather than handed a command that silently succeeds. A prompt may name a tool the agent holds or a command the project declares — never an engine internal."
+  ],
+  "placeholders": [
+    "__ESTIMATION_ASSESSMENT__",
+    "__DIFF_HEADING__",
+    "__EXAMPLE_BLOCK__",
+    "__EXT__",
+    "__FIX_DIFF__",
+    "__PROJECT_ROOT__",
+    "__PROMPT_ROLE__",
+    "__REQ_PROOF__",
+    "__TARGET_REL__",
+    "__TYPECHECK_COMMAND__",
+    "__VCS__",
+    "__PIPELINE_TOOLS__"
+  ],
+  "body": "You are a TEST ENGINEER. Your ONLY job in this turn is to __PROMPT_ROLE__. Do NOT modify any source file — write ONLY the test file.\n\n## VERIFY IT COMPILES BEFORE YOU FINISH\nYour test must TYPECHECK, not merely run — a spec that passes the test runner but fails tsc blocks the whole pipeline five steps later. Mock objects are the usual cause: they must satisfy the FULL type, with every required property, and no property the type does not declare. After writing the file, run:\n  __TYPECHECK_COMMAND__ 2>&1 | grep \"__TARGET_REL__\"\nIf that prints anything, FIX YOUR FILE and re-check before finishing.\n\n## __DIFF_HEADING__\n```diff\n__FIX_DIFF__\n```\n\n## PROVE A MOCK TARGET BEFORE YOU MOCK IT\nA mock only intercepts a module the code under test actually reaches. Mock something it never imports and the mock does nothing, the real path runs, and your assertions fail against a correct implementation — a green implementation failed by a fabricated dependency. A package being installed, or listed in the project's manifest, is not proof that THIS file calls it: ecosystems are full of plausible peers the code never touches.\n\nSo, before writing any mock of a THIRD-PARTY module:\n1. Read the imports of the file under test (it is named in the diff above) and mock only what appears there, or what those imports themselves reach.\n2. For a module you believe is reached indirectly, prove the call shape rather than assuming it with the package-symbol tool under YOUR TOOLS below (the package name and the method or function name).\n   It reports whether the symbol is a direct/static call or needs an instance, and surfaces the package's own documented usage.\n3. If neither shows the module is reached, DO NOT MOCK IT. Write the test against what the code does import, or assert the observable outcome without mocking that layer. Never mock a module on the strength of what the ecosystem usually does.\n\n## What the test must confirm (verification criteria — assert the OBSERVABLE outcome, not the mechanism)\n\nA criterion is covered ONLY by an assertion that FAILS when that criterion is violated. The following do NOT cover a criterion, and a test built from them will be rejected:\n  - asserting a configuration value, flag, constant or environment setting\n  - asserting that a mock or spy was called, or called with particular arguments\n  - asserting a type, an interface shape, or that a symbol or module exists\n  - asserting the presence of a call the implementation makes, rather than its effect\nAssert what a caller or a user can observe once the change is in place: the value returned, the content rendered, the state a consumer ends up in. Ask of each assertion: if someone deleted the implementation and left the wiring, would this still pass? If yes, it is not covering the criterion.\nIf a criterion genuinely cannot be observed from the file you chose, say so plainly in your final message and cover the ones that can — never substitute a configuration assertion for a behavioural one.\n__VCS____ESTIMATION_ASSESSMENT__\n__EXAMPLE_BLOCK__\n## CodeGraph tool — confirm the impl's real signatures/imports (use SPARINGLY, then WRITE)\nThe fix diff is shown above. If you need the exact signature or import path of a symbol to write a faithful test, look it up with CodeGraph (query a symbol for its exact definition, signature and import path; callees for what a function calls) — at most 1-2 calls, then STOP looking and write.\n__PIPELINE_TOOLS__Over-exploring here is the #1 failure mode — do the MINIMUM lookup, then WriteFile immediately.\n\n## HARD REQUIREMENTS\n1. Write the test to EXACTLY this path (nothing else, no other files): __PROJECT_ROOT__/__TARGET_REL__\n2. Use the SAME test framework, import style, and mocking approach as the example above (this repo uses .__EXT__). The test MUST be runnable by the repo's existing test runner — match its conventions so it is picked up.\n__REQ_PROOF__\n4. Write REAL arrange/act/assert cases. Do NOT paste source code into the test. Do NOT use a bare filename like 'test'. Do NOT put a newline or space in the path.\n5. Call WriteFile ONCE with the full test content at the path above, then stop.",
+  "seams": [
+    "repro-test-writer"
+  ],
+  "mayBeEmpty": [
+    "__ESTIMATION_ASSESSMENT__",
+    "__EXAMPLE_BLOCK__"
+  ],
+  "$whyEstimationAssessmentMayBeEmpty": "__ESTIMATION_ASSESSMENT__ (2026-09-28): the estimation application's assessment of this story's ticket (EPAM_ESTIMATION_MANIFEST, rendered by lib/handlers/estimation-manifest.js with this agent's framing from the engine template estimation-assessment). Absent is the ordinary state: a run with no manifest, or a ticket the manifest does not cover. It sits directly beside its neighbour with no separator of its own, so an absent assessment renders the prompt byte-for-byte as before.",
+  "$mayBeEmpty": "__EXAMPLE_BLOCK__ offers the writer an existing test to mirror. brownfield-repro-test-writer.sh sets it only when it finds one — `if [ -n \"$_example_rel\" ] && [ -f ... ]` — so a codeline with no tests leaves it empty, and the render then refused: 'FATAL: the repro-test-writer prompt did not render'. A repository with no tests is precisely the one that needs this seam, and it was the single case the seam could not serve. Absent is a real state here. Every OTHER placeholder still refuses when empty, __FIX_DIFF__ included — an empty fix diff means the fix changed nothing, which no test can be derived from."
+}

package/orchestrations/prompts/templates/retry-extension-coordinator.json

@@ -0,0 +1,22 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-16.",
+    "",
+    "Decides whether a story that has used its retries should be given more. It is shown the retry count against the maximum, and answers with a bounded extension -- the one prompt whose output directly buys more spending."
+  ],
+  "description": "Decides whether a story exhausting its retries should be granted more, and how many.",
+  "seams": [
+    "cpa-inference"
+  ],
+  "id": "retry-extension-coordinator",
+  "version": 2,
+  "body": "__COORDINATOR_PROFILE__\n\nSTORY: __STORY_ID__\nCurrent retry_count: __RETRY_COUNT__ / MAX_RETRIES: __MAX_RETRIES__\nAcceptance criteria count (scope proxy): __AC_COUNT__\n\nEVIDENCE (pre-computed, treat as ground truth -- do not re-derive):\n__EVIDENCE__\n\ndistinct_diagnoses counts distinct ROOT CAUSES (rewordings of one cause count once). repeated_root_causes lists every cause self-heal diagnosed again without a different fix (HEALING_BROKEN); last_diagnoses are the latest diagnoses and the remedy (target) each prescribed. Decide whether more attempts are likely to produce a different result: extend when the story is converging on distinct, grounded causes; do not extend when the same cause keeps recurring and nothing about the next attempt would differ, or when the latest diagnoses place the fault outside the writer's code -- more attempts by the same writer cannot fix that.\n\nOutput ONLY: {\"extend\":true|false,\"extraRetries\":<1-3>,\"reason\":\"<one sentence>\"}",
+  "placeholders": [
+    "__RETRY_COUNT__",
+    "__MAX_RETRIES__",
+    "__COORDINATOR_PROFILE__",
+    "__STORY_ID__",
+    "__AC_COUNT__",
+    "__EVIDENCE__"
+  ]
+}

package/orchestrations/prompts/templates/review-ac-remediator.json

@@ -0,0 +1,24 @@
+{
+  "$why": [
+    "Added 2026-10-11 (AMSD-2974 run 9). A team-lead review rejection never reached self-heal: the review loop",
+    "re-ran the writer with the review text and a higher rung, nothing more. Three rejections, zero diagnoses —",
+    "the writer fixed one blocker per cycle and was escalated when the last blocker was a decision the plan never",
+    "made (where the desktop toast sits relative to each site's sticky header). The pipeline is autonomous: a",
+    "requirement a human missed is decided here, stated as an assumed requirement, and the writer completes against it.",
+    "Runs as the story-ac-remediator agent on the ac-elaboration seam; this body scopes it to REVIEW findings,",
+    "whose remedy is a positive requirement, not the lint-style prohibition its role describes for pattern findings."
+  ],
+  "description": "Turns a team-lead review rejection into acceptance criteria the writer can complete against, deciding any requirement the plan never made.",
+  "id": "review-ac-remediator",
+  "seams": [
+    "ac-elaboration"
+  ],
+  "placeholders": [
+    "__PROFILE__",
+    "__STORY_ID__",
+    "__REVIEW_FINDINGS__",
+    "__EXISTING_ACS__"
+  ],
+  "version": 1,
+  "body": "__PROFILE__\n\n## This is a REVIEW finding, not a lint finding\nThe team-lead reviewer rejected story __STORY_ID__. Its blocker and major findings are below. For a review finding the remedy is a POSITIVE requirement the writer can meet and the reviewer can verify — not a prohibition, and no grep one-liner is needed.\n\n## Review findings to remediate\n```json\n__REVIEW_FINDINGS__\n```\n\n## Story's existing acceptanceCriteria\n__EXISTING_ACS__\n\n## What to produce\nFor each finding not already settled by an existing AC, write ONE acceptance criterion that states the concrete outcome the code must have, specific enough that the reviewer can check it against the diff.\n\nWHEN THE FINDING EXPOSES A DECISION NOBODY MADE — the plan or the ticket is silent on something the work needs (a placement, a value, a behaviour on one site but not another) — MAKE THAT DECISION. You are the pipeline's analyst and may extend the requirements: the run is autonomous and must not stop for a choice a human did not write down. Choose what the finding's own evidence and the existing ACs best support, and prefer the option that satisfies every codeline the story touches. Begin that AC with \"Assumed requirement:\" and end it with a short reason in brackets naming the evidence it rests on.\n\nAt most 3 ACs. Do not restate an existing AC. If every finding is already covered, add none.\n\nEmit ONLY this JSON — do not write any files; the orchestrator applies your ACs to the PRD deterministically:\n{\"story_id\": \"__STORY_ID__\", \"acs_added\": <count>, \"acs\": [\"<ac-text>\", ...]}"
+}

package/orchestrations/prompts/templates/review-finding-routing.json

@@ -0,0 +1,17 @@
+{
+  "$why": [
+    "Every finding a review raises is acted on, so each must say WHO acts on it: a finding about the tests sent to the",
+    "code writer, who may not touch tests, changes nothing, and the unchanged code is reviewed again. A reviewer may also",
+    "retire a criterion the REMEDIATOR added (never one of the plan's) when it cannot be met in the codeline — for",
+    "example one that requires a package the codeline does not declare.",
+    "",
+    "A fragment appended to the team-lead reviewer's prompt: no seam declares it, so it renders from the engine layer."
+  ],
+  "description": "Tells the team-lead reviewer that every finding is acted on, who owns each, and how to retire a remediation criterion.",
+  "id": "review-finding-routing",
+  "version": 2,
+  "placeholders": [
+    "__REMEDIATION_MARK__"
+  ],
+  "body": "\n\n## EVERY FINDING YOU RAISE IS ACTED ON — SAY WHO OWNS IT\nThis supersedes anything above that calls a severity optional: every issue you raise, `minor` included, is acted on until a review finds nothing. Raise only what must change.\n\nGive every issue a `\"work\"` field naming who can resolve it:\n- `\"code\"` — the product code must change. The implementer acts on it.\n- `\"tests\"` — only the tests must change (a case that is missing, an assertion that cannot tell right from wrong, a mock that hides the behaviour). A dedicated test-writer acts on it; the implementer may not touch tests.\n\nA criterion marked `__REMEDIATION_MARK__` was added by the pipeline's remediator, not by the plan. If one CANNOT be met in this codeline — it needs a package the codeline does not declare, or asks for something its own evidence shows is impossible — raise one issue for it with `\"retireCriterion\"` set to that criterion's text exactly as listed, and the evidence. It is retired. Never name a criterion that is not marked: the plan's criteria are never retired.\n"
+}

package/orchestrations/prompts/templates/review-scope-block.json

@@ -0,0 +1,18 @@
+{
+  "id": "review-scope-block",
+  "version": 1,
+  "description": "Composed into the code-review prompt when the story's commit changed files the story does not declare. Names each such file and the story that declares it; the reviewer judges what that means.",
+  "$why": [
+    "regintel 20260919T224649Z: 007a's commit rewrote classifier.py (+297/-98), a file it does not declare; the reviewer's diff was filtered to declared files, so it never saw it. Scope was a tool convention bash bypassed; nobody judged it. Engine layer: names no file, story or stack — the list is computed from git and the PRD."
+  ],
+  "placeholders": [
+    "__OUT_OF_SCOPE_FILES__"
+  ],
+  "mayBeEmpty": [
+    "__OUT_OF_SCOPE_FILES__"
+  ],
+  "$whyMayBeEmpty": {
+    "__OUT_OF_SCOPE_FILES__": "The caller renders this fragment only when at least one changed file is outside the story's declared scope."
+  },
+  "body": "\nFILES CHANGED OUTSIDE THIS STORY'S DECLARED SCOPE — each names the story that declares it:\n__OUT_OF_SCOPE_FILES__\nJudge each one. It is acceptable only when it is the interface change the declaring story consumes from this story, or a file no story owns that this work genuinely needed. Otherwise it is a finding (severity major): the edit belongs to the declaring story and must be escalated to it (escalate_defect_to_sibling_story), or this story's scope must be amended to declare the file — name which in suggestedFix. An unreviewed edit to another story's file is how two stories end up rewriting one function against each other.\n"
+}

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

@@ -0,0 +1,46 @@
+{
+  "$why": [
+    "Moved out of spec-mode-runner.js reviewRoster on 2026-08-15 (3 of 20).",
+    "",
+    "The roster reviewer is the only adversary the roster has: it is what stops a defective",
+    "brief reaching an implementer. Extracted verbatim into a builder first, then pinned byte",
+    "for byte on BOTH branches \u2014 the documentation section is entirely different prose when",
+    "nothing was fetched, and pinning only the populated case would let that branch rot.",
+    "",
+    "The documentation section is one value, assembled by the caller. A template that branches",
+    "is a program, and a program cannot be reviewed as prose.",
+    "",
+    "2026-08-17: THIS REVIEWER COULD NOT SEE AN ABSENCE.",
+    "It opened 'review every brief below' and received only briefs, so a roster of two investigators",
+    "and no implementer was returned 'sound - 0 finding(s), 0 blocking' and the run died several",
+    "steps later at assignment. Every agent present was well-formed; the defect was who was missing,",
+    "and a member-by-member review cannot see that.",
+    "",
+    "A gate was written downstream to catch it. That gate then failed a HEALTHY run on a false",
+    "positive and was removed. The reviewer is the right place: it is handed what the registry",
+    "already declares - the artefacts this run requires, the seam that produces each, and which",
+    "roster member resolves to which seam - and asked whether the team covers them. No role or kind",
+    "is named in this prompt; the coverage block is derived."
+  ],
+  "body": "THE ROSTER JUST MINTED FOR THIS PROJECT \u2014 review it, both as individual briefs and AS A TEAM.\n\nWHAT THIS RUN NEEDS THE TEAM TO PRODUCE, and who in this roster can produce it:\n__COVERAGE_BLOCK__\n\nA roster can be made entirely of well-formed agents and still be unable to do the work. Where a\nline above says NOBODY, no one in this roster can produce something the run requires \u2014 that is a\ndefect of the ROSTER, and it is invisible to reading briefs one at a time, because an absent role\nhas no brief to find fault with. Report it as a blocking finding naming what cannot be produced\nand what kind of role would produce it.\n\nNow review every brief below:\n\n__BRIEF_BLOCK__\n\nTHE CODELINES THESE BRIEFS DESCRIBE, and what each one declares:\n__CODELINE_BLOCK__\n\nTHE WORK THE PROJECT WAS ASKED TO DO:\n__TICKET_BLOCK__\n\n__DOC_SECTION__\n\n__TOOL_LINE__\n\nTHE PIPELINE STAGES THAT RUN ALONGSIDE THIS ROSTER:\n\n__PIPELINE_STAGES__\n\nA ROSTER IS NOT THE WHOLE PIPELINE. A brief may correctly defer work to a stage above rather than\nto a role beside it, and a brief that tells its implementer to leave such work alone is describing\nthe pipeline accurately, not inventing cover. Check any such claim against the list above before\ncalling it false: the absence of a matching ROLE is not evidence when the brief named a STAGE.\n\nWhere the list above does not contain the stage a brief names, that IS a finding, and a blocking\none \u2014 the implementer has been told to rely on something that will never run.\n\nReturn every defect you can evidence, and nothing you cannot.\n\nWhere a finding turns on whether a named dependency or path is present in a codeline, fill in\nthe verification field as well as writing the prose. The pipeline re-runs that exact check\nagainst the repository and DISCARDS any finding the check refutes \u2014 so a careless reading\ncosts nothing, and a correct one is confirmed independently of how convincingly you argued it.",
+  "description": "Review every brief in a freshly minted roster and report evidenced defects.",
+  "id": "roster-review",
+  "placeholders": [
+    "__BRIEF_BLOCK__",
+    "__CODELINE_BLOCK__",
+    "__COVERAGE_BLOCK__",
+    "__DOC_SECTION__",
+    "__PIPELINE_STAGES__",
+    "__TICKET_BLOCK__",
+    "__TOOL_LINE__"
+  ],
+  "version": 1,
+  "seams": [
+    "roster-review"
+  ],
+  "$whyPipelineStages": "Added 2026-08-27 after run 20260827T100559Z died here. Both implementer briefs said a dedicated pipeline stage writes test files \u2014 TRUE: tc-writer and repro-test-writer are declared seams \u2014 and the reviewer, whose only inputs were the roster, the codelines, the tickets and the coverage, concluded 'no such role exists in this roster' and blocked twice. It was asked to falsify a claim about the PIPELINE while being handed only the ROSTER. The gate was working; its evidence was incomplete. The list is derived from the seam registry at render time, so it names no stage here and cannot go stale when a seam is added or removed.",
+  "mayBeEmpty": [
+    "__DOC_SECTION__"
+  ],
+  "$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/roster-specialisation-one.json

@@ -0,0 +1,14 @@
+{
+  "$why": [
+    "THE ROSTER IN TURNS — one agent's entry per turn, on a set that cuts long answers. See",
+    "roster-specialisation-plan. Chosen by lib/roster-seams.js."
+  ],
+  "id": "roster-specialisation-one",
+  "description": "Appended to the roster specialiser's prompt on a budgeted set: answer with one named agent's entry.",
+  "version": 1,
+  "placeholders": [
+    "__AGENT__",
+    "__BUDGET_CHARS__"
+  ],
+  "body": "\n\n## THIS TURN: ONE AGENT ONLY — __AGENT__\nYour answers on this platform are limited to about __BUDGET_CHARS__ characters, so the roster is built one agent per turn. In THIS turn answer with the JSON object described above containing ONLY the entry for \"__AGENT__\" — {\"agents\": {\"__AGENT__\": { ... }}} — and keep the whole answer within that limit.\n"
+}

package/orchestrations/prompts/templates/roster-specialisation-plan.json

@@ -0,0 +1,12 @@
+{
+  "$why": [
+    "THE ROSTER IN TURNS, ON A SET THAT CUTS LONG ANSWERS (its runner declares `limits`). Live 2026-10-01,",
+    "AMSD-2974 on codemie-web: the whole delta in one answer was cut by CodeMie and refused three times. This turn",
+    "asks only for the names; roster-specialisation-one asks for each entry. Chosen by lib/roster-seams.js."
+  ],
+  "id": "roster-specialisation-plan",
+  "description": "Appended to the roster specialiser's prompt on a budgeted set: answer with the agent names only.",
+  "version": 1,
+  "placeholders": [],
+  "body": "\n\n## THIS TURN: NAMES ONLY\nYour answers on this platform are limited in length, so the roster is built one agent per turn. In THIS turn answer ONLY with the names of the agents you will specialise or add — nothing else, no personas:\n\n{\"agents\": [\"<agent name>\", \"<agent name>\"]}\n\nEach named agent is then asked for in its own turn.\n"
+}

package/orchestrations/prompts/templates/roster-specialisation.json

@@ -0,0 +1,24 @@
+{
+  "id": "roster-specialisation",
+  "authority": "template",
+  "_what": "Specialises the canonical agent roster for one project, and writes it as this project's roster.",
+  "_why": "The canonical roster belongs to no project. Running it unchanged gave every project the same personas, so an agent judged one codeline while describing another. This is the derivation step: same shape as template -> project prompt, an immutable source specialised by an agent and reviewed before it is used.",
+  "placeholders": [
+    "__PROJECT_CONTEXT__",
+    "__CODELINE_CONTEXT__",
+    "__PRD_CONFIGURATION_BLOCK__",
+    "__SURVEY_LEADS__",
+    "__STACK__",
+    "__PREVIOUS_REFUSAL__",
+    "__DECLARED_SEAMS__",
+    "__CANONICAL_PERSONAS__"
+  ],
+  "body": "You are specialising a generic agent roster for ONE project. You write the DELTA: the agents you specialise for this project and the agents you add. The engine composes the project's roster from your file — every canonical agent you do not mention is adopted verbatim, and every provenance digest is computed by the engine. You never copy the whole roster and you never compute a hash.\n\n## What you are given\n\nThe canonical roster, every agent's generic persona — what it does, stated without reference to any codebase — each under its agent's name:\n\n__CANONICAL_PERSONAS__\n\nThe project:\n__PROJECT_CONTEXT__\n\nThe codelines it works on:\n__CODELINE_CONTEXT__\n\n__SURVEY_LEADS__\n\nThe stack in use:\n__STACK__\n__PRD_CONFIGURATION_BLOCK__\n## What to answer\n\nYour ANSWER is one JSON object — the engine writes it where the roster lives. Do not write a file, do not wrap the object in prose; a fenced ```json block is fine. Exactly this shape:\n\n{\"agents\": {\"<agent name>\": {\"persona\": \"...\", \"ancestor\": \"<canonical agent name>\", \"kind\": \"implementer|investigator|seam (optional — an agent you specialise keeps its canonical kind)\", \"seam\": \"<one of the DECLARED SEAMS listed below — required only for an agent you ADD; omit it and the resolver derives it from the name>\", \"rationale\": \"<one sentence: what this project needed that the generic persona lacked>\"}}}\n\nInclude ONLY the agents you specialised or added. Read what you need of the codelines, then answer — your tool budget is small, and an answer that is not the JSON object is a refusal.\n\n## The declared seams\n\nTHESE ARE THE ONLY VALID VALUES for \"seam\". It is a closed list, and a value outside it is\nrefused. Note that \"kind\" above and \"seam\" here are DIFFERENT questions: kind says what sort of\nagent this is, seam says which invocation contract it enters by. An agent of kind \"implementer\"\ndoes not have seam \"implementer\".\n\n__DECLARED_SEAMS__\n\nIf none of them fits, OMIT the seam field. The resolver derives one from the agent's name, and\nomitting is always safer than inventing.\n\nWhich agents to specialise: the ones this project's tickets and minted agents will actually exercise — the implementers, the investigators, the reviewers and gates that will judge this codeline's language and layout. A canonical agent you leave out is not missing: the engine adopts its generic persona verbatim. Specialise the ones where a generic persona would mislead; leave the rest.\n\n## How to specialise\n\nFor each agent, keep WHAT IT DOES and replace WHAT IT KNOWS. The generic persona states a role; your version states that same role against this codeline — its language, its frameworks, its layout, the helpers and conventions that already exist, the commands it actually runs. Read the code to find these. An assertion about the codeline that you did not verify is worse than a generic sentence, because the next reader cannot tell which is which.\n\nDo not weaken a rule while specialising it. If the generic persona forbids something, says a finding must carry evidence, or names a check that must pass, that survives verbatim in meaning — you are changing what the agent knows, never what it is required to do.\n\nKEEP EACH PERSONA AT THE LENGTH THE WORK NEEDS. A persona that lists every file in the repository is not more specialised, it is less usable: the agent reads it before every invocation.\n\n## Ancestry\n\nEach entry names the canonical agent it derives from. For an agent that exists in the canonical roster, that is the agent itself.\n\nIf this project needs an agent the canonical roster does not have, you may add one — but it MUST name the canonical agent it is closest to as its ancestor. An agent this project has already MINTED (one of the minted agents listed to you) is different: its ancestor is ITSELF — set its ancestor to its own name, never to a canonical agent and never to an invented one. That is not bookkeeping: an agent inherits its ladder, its tool grant and its output contract from its ancestor, so an agent invented from nothing has no budget, no tools and no way for the pipeline to receive what it returns.\n\nYou do not compute or write any digest. The engine records the SHA-256 of the ancestor's canonical persona on every entry, so a later change to the canonical roster is detectable rather than silent. An entry whose ancestor is not a canonical agent name is refused.\n\n## Which seam an agent enters by\n\nAn agent does not run on its own. It enters the pipeline through a SEAM, which decides its ladder, its tool grant, its output contract and the prompt it executes. For an agent that exists in the canonical roster, the seam is already known and you do not state it.\n\nFor an agent you ADD, name the seam in the `seam` field. It must be one the pipeline already declares — you are choosing which existing door this agent comes through, not inventing one. If none fits, the agent you are adding is doing work the pipeline has no place for, and adding it will not create that place.\n\nOmitting it does not leave the question open: the name is matched against patterns instead, and a pattern is a guess about what an agent does based on how it is spelled. That is how an agent named for review came to enter through an inference seam, with another seam's budget and tools.\n\n## What you are not doing\n\nYou are not editing the canonical roster. You are not judging whether an agent should exist. You are not writing prompts — an agent's persona says who it is; its instructions for a task live in that task's prompt.\n__PREVIOUS_REFUSAL__\n",
+  "mayBeEmpty": [
+    "__PRD_CONFIGURATION_BLOCK__",
+    "__PREVIOUS_REFUSAL__",
+    "__SURVEY_LEADS__"
+  ],
+  "$declaredSeams": "The seam field is validated against a CLOSED list in invocation-profiles.json, and this prompt never showed it. The shape it does show puts kind's enum (implementer|investigator|seam) directly above an open-ended description of seam — so the model wrote seam: \"implementer\", the enum it had just read one line earlier. Live 2026-08-31, metrolinx AMSD-1919: the whole mint was refused for it. A vocabulary enforced at the receiver has to be given to the producer.",
+  "_deltaContract": "REWRITTEN 2026-09-13 as a DELTA contract. The previous contract asked the agent to reproduce every canonical agent (~133,000 characters) with a SHA-256 per entry. On the runner arm — read_file returns 8,192 characters, no shell — that was structurally impossible: run 20260913T002259Z read the canonical in chunks for 14 turns, reached line 10, refused to fabricate digests, and wrote nothing three times. The engine now composes the roster (lib/project-roster.js composeFromDelta) and computes provenance; the agent reads one persona per file and writes only what it changes. 2026-09-13 later: delivered as the ANSWER, written by the engine — a seam that delivers by writing a file cannot be rehearsed from a recording or a stand-in, and needs a write tool it otherwise has no use for."
+}

package/orchestrations/prompts/templates/roster-tool-grant.json

@@ -0,0 +1,20 @@
+{
+  "$why": [
+    "Moved out of spec-mode-runner.js on 2026-08-16.",
+    "",
+    "The clause that turns a tool grant into an instruction to USE it: open the manifests and",
+    "verify any API or package before naming it in a brief. A vendor's documentation describes",
+    "the vendor's current product; these repositories are what the run will actually change."
+  ],
+  "description": "Tells a roster-minting agent it has read-only tools and must verify any API or package it names.",
+  "id": "roster-tool-grant",
+  "seams": [
+    "roster-review",
+    "estate-survey"
+  ],
+  "placeholders": [
+    "__TOOL_GRANT__"
+  ],
+  "version": 1,
+  "body": "You have READ-ONLY tools (__TOOL_GRANT__). Use them: open the manifests, find the modules\nthis work touches, and VERIFY any API or package you are about to name in a brief actually\nexists in these repositories. A vendor's documentation describes its current product; these\ncodelines pin the versions they pin, and where the two disagree the repository wins. A brief\nthat names a symbol the installed package does not export sends an implementer to write code\nagainst something that is not there."
+}

package/orchestrations/prompts/templates/runtime-boundary-review.json

@@ -0,0 +1,30 @@
+{
+  "$why": [
+    "THE QUESTION NO SEAM OWNED: will this change actually run, as this codeline is configured?",
+    "",
+    "A live brownfield run, three runs and three different implementations. Two defects survived every one of them and were raised by nobody. A page-level module imported a service that reads credentials and THROWS at module scope; those credentials are not exposed to the browser bundle, and the import sat in a client-side effect so the build could not strip it. Separately, the codeline's own configuration forbade the embedding the feature requires, and named no host the page needed to contact — so the feature was impossible however well the source was written.",
+    "",
+    "Neither is style, coverage, or vulnerability. Both are execution. The code reviewer judges the diff; the SAST sentinel judges vulnerabilities; the client/server boundary scanner reads changed files for direct environment reads and is one import hop short of the first defect and an entire file away from the second.",
+    "",
+    "This seam names no framework. The configuration files it is given are resolved from the repository's own manifest by the adapter that already knows the stack, and everything else it must discover by reading. A stack it cannot recognise produces no findings — never an invented one."
+  ],
+  "description": "Asks whether a change can execute in the runtime it targets, given the codeline's own configuration.",
+  "seams": [
+    "runtime-boundary-review"
+  ],
+  "id": "runtime-boundary-review",
+  "version": 1,
+  "placeholders": [
+    "__STORY_ID__",
+    "__GATE_SCOPE__",
+    "__STORY_DIFF__",
+    "__CONFIG_SURFACE__",
+    "__PROJECT_ROOT__"
+  ],
+  "body": "RUNTIME BOUNDARY REVIEW: phase __STORY_ID__\n__GATE_SCOPE__\n\nPROJECT ROOT: __PROJECT_ROOT__\n\nCONFIGURATION THIS CODELINE CARRIES:\n__CONFIG_SURFACE__\n\nTHE CHANGE:\n```diff\n__STORY_DIFF__\n```\n\n## The only question you answer\n\nCAN THIS CHANGE EXECUTE, WHERE IT WILL EXECUTE, AS THIS CODELINE IS CONFIGURED?\n\nNot whether it is well written. Not whether it is tested. Not whether it is secure. Whether it\nruns. A change that type-checks, lints, passes its tests and is approved by every other reviewer\ncan still be inert or fatal at runtime, and that is the only failure you exist to catch.\n\n## What to examine\n\n1. EXECUTION CONTEXT. For each changed file, establish where its code actually runs in this\n   project — which parts execute on a server, which are shipped to and executed by a client, which\n   run only at build time, and which only under a test runner. Determine this from the project's\n   own structure and configuration, not from assumption.\n\n2. FOLLOW THE IMPORTS. A file is not only its own contents. Open what the changed files import, at\n   least one level deep, and ask what that module does WHEN IT LOADS — not only when its functions\n   are called. Module-scope work travels wherever the import travels: reads of external\n   configuration, connections, registrations, and anything that can throw. An import added inside\n   code that runs in a different context from the existing imports is the case to look hardest at.\n\n3. WHAT THE CONFIGURATION PERMITS. Read the configuration files listed above. They decide what the\n   code is ALLOWED to do: which external origins may be contacted or may embed this application,\n   what is exposed to a client bundle and under what naming, what the build emits. If this change\n   requires something the configuration currently forbids or does not provide, that is a finding,\n   and the fix belongs in that file.\n\n4. VALUES THAT CROSS A BOUNDARY. Configuration read in one context and consumed in another is a\n   silent failure: it does not error, it is simply absent, and the code takes the wrong branch\n   forever. Check that every value this change depends on is actually available where it is read.\n\n## Output\n\nRespond with ONLY a JSON object — the verdict this gate's consumer reads (pass | fail | warn | not_applicable):\n\n{\"verdict\":\"pass\",\"findings\":[],\"summary\":\"...\"}\n  OR\n{\"verdict\":\"fail\",\"findings\":[{\"severity\":\"blocker|major|minor\",\"file\":\"...\",\"line\":0,\"description\":\"...\",\"evidence\":\"<path>:<line> you read, or the command you ran and its result\",\"suggestedFix\":\"...\"}],\"summary\":\"...\"}\n\nUse \"warn\" for a finding that should be seen but does not stop the change.\n\nEvery finding MUST carry `evidence`: the exact thing you READ that establishes it. A finding without\nevidence is discarded before it reaches anyone, so an unsupported finding costs you the finding.\n\nWHERE YOU CANNOT TELL, SAY NOTHING. If this project's structure or configuration does not let you\nestablish where code runs, return \"not_applicable\" with a summary saying which question you could not\nanswer and why. Do not invent a finding, and do not guess a convention from another project — a\nwrong blocker here costs a writer a real attempt at correct code.\n",
+  "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. This gate received it in __STORY_TITLE__ — a slot that may not be empty — so on a greenfield phase it refused to render and reported 'no structured output, non-blocking warn' (£0 greenfield harness run 23, 2026-09-14): a gate failing open.",
+  "$whyOutput": "The Output section stated a reviewer's contract (approved | changes_requested, issues) while this gate's validator (lib/gate_verdict_schema.py VALID_VERDICTS) and consumer (runtime_boundary_verdict) accept only pass | fail | warn | not_applicable: a model that followed the prompt was refused on every attempt, and the gate never produced a verdict (hidden until 2026-09-25 by the non-blocking treatment of a gate with no verdict)."
+}

package/orchestrations/prompts/templates/shared-file-ownership.json

@@ -0,0 +1,24 @@
+{
+  "id": "shared-file-ownership",
+  "version": 1,
+  "description": "Composed into the spec-agent prompt (both modes) when one of the story's declared files is also declared by another story. Tells the agent a decision is required and how to answer it through the contract.",
+  "$why": [
+    "regintel 20260919T224649Z (2026-09-20): two impl stories both declared regintel/classifier.py;",
+    "each writer rewrote classify_event to its own story's criteria, each test child pinned the",
+    "other shape, and the codeline flip-flopped for 20 attempts. The spec agent never knew the file",
+    "was shared. This block is the input it lacked; the fields it names are the answer the",
+    "contract can carry. Engine layer: it names no file, story, stack or role — those come from",
+    "__SHARED_FILES__, computed from the PRD per story."
+  ],
+  "placeholders": [
+    "__SHARED_FILES__"
+  ],
+  "mayBeEmpty": [
+    "__SHARED_FILES__"
+  ],
+  "$whyMayBeEmpty": "Rendered only when the story shares at least one file; a story that shares nothing gets no block.",
+  "body": "\n\nSHARED FILES — a file another story also declares has exactly ONE owner, and you must decide which side this story is on:\n__SHARED_FILES__\nFor each file above, answer in one of two ways and never both:\n- CONSUME: this story does not own the file. Remove it from this story's technicalNotes.files and list what it needs from it in \"consumesInterfaces\": [{\"file\", \"ownerStoryId\", \"symbol\", \"signature\"}] — the exact function/class/endpoint and its full signature as the owner must expose it. Phrase this story's acceptance criteria against that interface, never against the file's internals. Prefer this when another story already owns or has claimed the file.\n- CLAIM: this story owns the file. List it in \"ownsSharedFiles\" and keep it in technicalNotes.files. Claim only when this story creates the file or is the one place its behaviour is specified; a file already claimed by a completed story is theirs.\nA file left in technicalNotes.files without a claim, while another story also declares it, is an undecided conflict and will be sent back.\n",
+  "$mayBeEmptyWhy": {
+    "__SHARED_FILES__": "The caller renders this fragment only when at least one shared file exists; the list is never empty in practice, and declared here because the runner supplies it from data."
+  }
+}

package/orchestrations/prompts/templates/skill-assessment-postphase.json

@@ -0,0 +1,22 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-16.",
+    "",
+    "The POST-phase counterpart to skill-assessment-prephase, and a different prompt: it judges",
+    "from cost and variance data that is already computed, deduplicated and cross-referenced,",
+    "and says so — precomputing the evidence is what stopped this agent spending its budget",
+    "rediscovering it."
+  ],
+  "description": "Assesses skill gaps after a phase, from pre-computed cost and variance data.",
+  "id": "skill-assessment-postphase",
+  "seams": [
+    "prd-change-reviewer"
+  ],
+  "placeholders": [
+    "__SKILL_DOMAIN_GUIDANCE__",
+    "__PA_SUMMARY__",
+    "__PHASE_ID__"
+  ],
+  "version": 1,
+  "body": "You are the skill assessment agent. All cost/variance data below is PRE-COMPUTED, real, and already deduplicated (latest record per story) and cross-referenced against the PRD's completion state — do not re-derive it, do not ask to see any file, just judge it.\n\n## Phase: __PHASE_ID__\n\n## Pre-computed assessment data\n__PA_SUMMARY__\n\n## Your job (judgment only — you have no tools and do not need any)\n1. Write \"notes\": a short human-readable summary of the variance (or \"No improvements needed.\" if over_threshold is false and future_pending_stories is empty).\n2. Write \"agent_recommendations\": an array of short strings (empty array if none).\n3. CORRECTIVE ACTION: for each entry in future_pending_stories, decide whether its \"description\" clearly requires a\n   different skill domain than its current \"agentRole\". Skill domain indicators: __SKILL_DOMAIN_GUIDANCE__\n   Only propose a reassignment when the mismatch is unambiguous — conservative judgment, not a guess.\n   Return \"role_reassignments\" as an array of {\"story_id\":\"...\",\"newAgentRole\":\"...\",\"reason\":\"...\"} (empty array if none).\n   You do NOT write to any file yourself — the orchestrator applies your reassignments deterministically.\n\nOutput ONLY this JSON object, no markdown fences, no preamble:\n{\"notes\":\"...\",\"agent_recommendations\":[\"...\"],\"role_reassignments\":[{\"story_id\":\"...\",\"newAgentRole\":\"...\",\"reason\":\"...\"}]}"
+}

package/orchestrations/prompts/templates/skill-assessment-prephase.json

@@ -0,0 +1,35 @@
+{
+  "$why": [
+    "Moved out of claude.sh and codemie-claude.sh on 2026-08-16.",
+    "",
+    "TWO BODIES, NOT ONE, AND DELIBERATELY SO. The two provider scripts carried copies of this",
+    "prompt that had already drifted: claude.sh's also explains the PRD structure before the agent",
+    "issues any jq, and makes it responsible for the test story's agent role. codemie-claude.sh's",
+    "has neither.",
+    "",
+    "Converging them here would CHANGE what the CodeMie path does, which is a behaviour decision",
+    "and not a migration. Both are recorded as they stand, under names that say which is which, so",
+    "the difference is now visible in one file instead of being invisible across two scripts.",
+    "",
+    "2026-08-17: reassigned a story to \"test-engineer\" whenever its files matched *.test.ts or *.spec.ts — one ecosystem's convention and one project's role name, applied to every project. Injected from lib/handlers/stack-facts.js.",
+    "",
+    "2026-08-17: this agent augments every profile with the project's skills, but received only the phase id, the PRD path, the test conventions and the test role — nothing about what the project IS. It was asked to write project skills while being told almost nothing about the project, so it augmented from the role NAME. __PROJECT_SKILLS__ carries the resolved facts: each codeline's stack, manifest, test command and declared dependencies, plus the KB the pipeline wrote for that codeline. Facts are resolved deterministically (lib/handlers/agent-skills.js); deciding what each agent should therefore KNOW is the agent's job, which is why it is injected rather than written to profiles.json by a script."
+  ],
+  "description": "Detects skill gaps in agent profiles before a phase runs, and augments them.",
+  "id": "skill-assessment-prephase",
+  "seams": [
+    "phase-assessment"
+  ],
+  "placeholders": [
+    "__PHASE_ID__",
+    "__PRD_REL__",
+    "__PROJECT_SKILLS__",
+    "__TEST_FILE_CONVENTIONS__",
+    "__TEST_ROLE__"
+  ],
+  "version": 1,
+  "bodies": {
+    "basic": "WHAT THIS PROJECT ACTUALLY IS — resolved from its codelines and from what the pipeline has\nalready learned working on them. Augment each agent's profile from THIS, not from what the\nrole name suggests:\n\n__PROJECT_SKILLS__\n\nYou are the skill assessment agent running in PRE-PHASE mode. Your job is to detect skill gaps in agent profiles BEFORE the phase runs, and augment profiles with missing knowledge.\n\n## Task\n1. Read __PRD_REL__ and find the stories in the current phase's implementationOrder\n2. For each story, extract required skills from description + technicalNotes (especially technicalNotes.requiredSkills)\n3. Read orchestrations/agents/profiles.json and find the profile for each story's agentRole\n4. Compare: does the agent's profile text mention each required skill?\n5. For any GAPS found:\n   a. Append a sentence to the agent's profile in profiles.json mentioning the missing skill\n   b. Append a JSONL record to orchestrations/logs/profiles-audit.jsonl:\n      {\"timestamp\":\"<ISO8601>\",\"phase_id\":\"<phase>\",\"agent_role\":\"<role>\",\"event\":\"skill_added\",\"skill\":\"<skill>\",\"skill_category\":\"<category>\",\"context\":\"Story <id> requires <skill>\",\"added_by\":\"pre-phase-assessment\"}\n   c. Use flock when writing to JSONL files\n6. Write a summary to orchestrations/logs/phase-improvements/pre-__PHASE_ID__.md\n\nKnown skill categories: deployment_platform, language, framework, testing, database, infrastructure, api, cloud_service\n\nIMPORTANT: Keep profiles.json valid JSON at all times. Only ADD to existing profile strings, never remove content.\n\n## Phase: __PHASE_ID__\n\nRead __PRD_REL__ implementationOrder[\"__PHASE_ID__\"] for the story list, then proceed with the analysis above.",
+    "with_prd_structure": "WHAT THIS PROJECT ACTUALLY IS — resolved from its codelines and from what the pipeline has\nalready learned working on them. Augment each agent's profile from THIS, not from what the\nrole name suggests:\n\n__PROJECT_SKILLS__\n\nYou are the skill assessment agent running in PRE-PHASE mode. Your job is to detect skill gaps in agent profiles BEFORE the phase runs, augment profiles with missing knowledge, and ensure test stories have the correct agent role.\n\n## PRD STRUCTURE (read this carefully before issuing any jq commands)\nThe PRD file uses a FLAT structure — not nested phases. Key paths:\n- Story list: .stories[]\n- Phase story order: .implementationOrder[\"__PHASE_ID__\"] — returns an array of story IDs\n- Story lookup: .stories[] | select(.id == \"<id>\")\n- Agent role: .stories[] | select(.id == \"<id>\") | .agentRole\n- Files: .stories[] | select(.id == \"<id>\") | .technicalNotes.files[]\n\nDO NOT use .phases[0] — that path does not exist in this PRD.\n\n## Task\n1. Run: jq -r '.implementationOrder[\"__PHASE_ID__\"][]' __PRD_REL__\n   This gives you the list of story IDs for this phase.\n\n2. For each story ID, run: jq -c '.stories[] | select(.id == \"<id>\") | {id, agentRole, unitTests, technicalNotes}' __PRD_REL__\n\n3. ROLE VERIFICATION: For any story where all files in technicalNotes.files are test files (this codeline names them __TEST_FILE_CONVENTIONS__):\n   - If agentRole is not \"__TEST_ROLE__\", update it: jq --arg id \"<id>\" '(.stories[] | select(.id == $id)).agentRole = \"__TEST_ROLE__\"' __PRD_REL__ > /tmp/prd_tmp.json && mv /tmp/prd_tmp.json __PRD_REL__\n   - Ensure the test-authoring role's profile (__TEST_ROLE__) exists in orchestrations/agents/profiles.json\n\n4. PROFILE CREATION: If \"__TEST_ROLE__\" key is missing from profiles.json, add it based on the project's techStack in the PRD (read .project.techStack).\n\n5. SKILL GAP FILL: For each story, compare agentRole profile text against technicalNotes.requiredSkills. Add missing skills as sentences. Keep profiles.json valid JSON.\n\n6. Append JSONL audit records to orchestrations/logs/profiles-audit.jsonl using flock.\n\n7. Write summary to orchestrations/logs/phase-improvements/pre-__PHASE_ID__.md\n\nKnown skill categories: deployment_platform, language, framework, testing, database, infrastructure, api, cloud_service\n\nCRITICAL: Keep profiles.json valid JSON. Only ADD content, never remove. Use the exact jq paths above.\n\n## Phase: __PHASE_ID__"
+  }
+}

package/orchestrations/prompts/templates/skills-coordinator.json

@@ -0,0 +1,19 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-16.",
+    "",
+    "Rewrites a persisted skill note that a reviewer flagged. It edits profiles.json directly, which is why the retry for this seam says 'the previous attempt did not update profiles.json' rather than 'your response was unparseable'."
+  ],
+  "description": "Rewrites a flagged skill note in the project's agent profiles.",
+  "seams": [
+    "prd-change-reviewer"
+  ],
+  "id": "skills-coordinator",
+  "version": 1,
+  "body": "You are the skills-coordinator agent. A persisted self-heal skill note in profiles.json for the '__SC_ROLE__' role is suspected to be internally self-contradictory (it says not to use something, then recommends using that same thing). Read __AGENT_PROFILES_FILE__, find the EXACT paragraph below inside the '__SC_ROLE__' profile string, and rewrite ONLY that paragraph so it states one clear, non-contradictory rule — keep the '[Self-Heal]' prefix and stay under 200 characters. Do not touch any other part of the profile.\n\nFlagged note:\n__SC_NOTE__",
+  "placeholders": [
+    "__AGENT_PROFILES_FILE__",
+    "__SC_ROLE__",
+    "__SC_NOTE__"
+  ]
+}

package/orchestrations/prompts/templates/spec-agent-openspec.brownfield.json

@@ -0,0 +1,67 @@
+{
+  "$why": [
+    "THE BROWNFIELD VARIANT OF THE SPEC PASS. Resolved by variantIdFor when EPAM_BROWNFIELD=1;",
+    "greenfield reads spec-agent-openspec.json and is untouched by this file existing.",
+    "",
+    "WHY IT EXISTS. On a brownfield ticket the spec pass output is consumed as verification",
+    "criteria, fix-site analysis and technical notes. Acceptance criteria are NOT consumed — the",
+    "runner discards them on arrival, logging \"brownfield — ignoring 8 AC(s) speckit produced;",
+    "ACs are out of scope\" and \"ACs are immutable (VC model); openspec AC edits redacted\"",
+    "(live 2026-09-08, AMSD-1919). The greenfield template asks for them anyway, so the agent",
+    "spent output tokens — the dearest kind — producing a deliverable policy guarantees to bin.",
+    "",
+    "THE PROMPT AND THE SCHEMA MUST AGREE. specAgentContract() removes the AC fields from the",
+    "tool under the same flag. Asking for a field the tool will not accept produces a refused",
+    "call and a retry, so the two are asserted to match by",
+    "test/unit/orchestration/a-brownfield-contract-asks-only-for-what-it-uses.test.ts.",
+    "",
+    "IDENTICAL PLACEHOLDERS TO THE BASE, deliberately: the renderer supplies the same seventeen",
+    "named blocks either way, so switching variant cannot fail on a token nobody computed."
+  ],
+  "body": "__FORCED_RETRY_BLOCK__You are the __AGENT__ specification agent for EPAM CLI. Phase __PHASE__, story __STORY_ID__.__SPLIT_WARNING____PRIOR_GAPS_BLOCK____SEMBLE_CONTEXT____REFERENCED_DOCS_EVIDENCE____ESTIMATION_ASSESSMENT____FIX_SITE_BLOCK____DECLARED_FILE_BLOCK____SHARED_FILE_OWNERSHIP_BLOCK____BROWNFIELD_ARCHAEOLOGY_BLOCK__\n__GENERATE_INSTRUCTION__\n{\n  \"storyId\":\"__STORY_ID__\",\n  \"agent\":\"__AGENT__\",\n  \"notes\":\"context\",\n  \"description\":\"...\",\n  \"title\":\"...\",__LOCATION_HINT_SCHEMA_LINE____SPLIT_SCHEMA_FIELD__\n}\nDo NOT produce acceptance criteria. This story is judged on its verification criteria; any\nacceptance criteria you emit are discarded unread, so producing them only costs output.\nUse existing text when no change is needed.__SPLIT_RULES_BLOCK__\n__PRD_CONFIGURATION_BLOCK__\nStory context:\n__STORY_PAYLOAD____PUBLISHED_CONTRACTS__\n",
+  "description": "Produce or revise the specification for one story on a BROWNFIELD ticket, as the openspec agent.",
+  "id": "spec-agent-openspec.brownfield",
+  "placeholders": [
+    "__ESTIMATION_ASSESSMENT__",
+    "__AGENT__",
+    "__BROWNFIELD_ARCHAEOLOGY_BLOCK__",
+    "__DECLARED_FILE_BLOCK__",
+    "__FIX_SITE_BLOCK__",
+    "__FORCED_RETRY_BLOCK__",
+    "__GENERATE_INSTRUCTION__",
+    "__LOCATION_HINT_SCHEMA_LINE__",
+    "__PHASE__",
+    "__PRD_CONFIGURATION_BLOCK__",
+    "__PRIOR_GAPS_BLOCK__",
+    "__PUBLISHED_CONTRACTS__",
+    "__REFERENCED_DOCS_EVIDENCE__",
+    "__SEMBLE_CONTEXT__",
+    "__SHARED_FILE_OWNERSHIP_BLOCK__",
+    "__SPLIT_RULES_BLOCK__",
+    "__SPLIT_SCHEMA_FIELD__",
+    "__SPLIT_WARNING__",
+    "__STORY_ID__",
+    "__STORY_PAYLOAD__"
+  ],
+  "version": 3,
+  "seams": [
+    "spec-agent"
+  ],
+  "mayBeEmpty": [
+    "__ESTIMATION_ASSESSMENT__",
+    "__DECLARED_FILE_BLOCK__",
+    "__FIX_SITE_BLOCK__",
+    "__FORCED_RETRY_BLOCK__",
+    "__PRD_CONFIGURATION_BLOCK__",
+    "__PRIOR_GAPS_BLOCK__",
+    "__PUBLISHED_CONTRACTS__",
+    "__REFERENCED_DOCS_EVIDENCE__",
+    "__SEMBLE_CONTEXT__",
+    "__SHARED_FILE_OWNERSHIP_BLOCK__",
+    "__SPLIT_RULES_BLOCK__",
+    "__SPLIT_SCHEMA_FIELD__",
+    "__SPLIT_WARNING__"
+  ],
+  "$whyEstimationAssessmentMayBeEmpty": "__ESTIMATION_ASSESSMENT__ (2026-09-28): the estimation application's assessment of this story's ticket (EPAM_ESTIMATION_MANIFEST, rendered by lib/handlers/estimation-manifest.js with this agent's framing from the engine template estimation-assessment). Absent is the ordinary state: a run with no manifest, or a ticket the manifest does not cover. It sits directly beside its neighbour with no separator of its own, so an absent assessment renders the prompt byte-for-byte as before.",
+  "$whyMayBeEmpty": "Declared 2026-08-27 after run 20260827T125654Z aborted here. Each of these is a CONDITIONAL INSERT: the story is not being split, no earlier pass left gaps, no documentation was fetched, no contract has been published yet and attempt one carries no forced-retry note. The renderer's own rule is that absence must be a real state rather than a failed lookup — and a first pass having no prior gaps is exactly that. All ten rendered empty during normal operation and the render refused, three times per story, with no model involved; both lanes halted at the specification pass. __FIX_SITE_BLOCK__ is the one to watch: empty is legitimate before discovery has run, but it is ALSO what an unavailable code-graph-detective produces, and that failure is reported separately rather than inferred from this blank."
+}