amsd-pipeline-shared 0.5.11 → 0.5.13

package/orchestrations/prompts/templates/guard-vocabulary-codegraph.json

@@ -0,0 +1,25 @@
+{
+  "$why": [
+    "A FRAGMENT of guard-vocabulary, 2026-08-15. It appears only when there is a repository",
+    "index to verify against; with none, the parent prompt must not carry a heading implying",
+    "the agent can check something it cannot.",
+    "",
+    "It is its own template rather than a string in code because the rule is that EVERY prompt",
+    "lives in the template layer — a conditional section is still prompt text, and putting it",
+    "in a helper would have quietly re-created the thing this migration removes.",
+    "",
+    "The leading newline lives HERE, not in the parent. Put in the parent it produced a blank",
+    "line in exactly the branch where no index exists — visible only in the case with no",
+    "evidence, which is the case least likely to be looked at."
+  ],
+  "body": "\nVERIFY BEFORE YOU ANSWER — you have a real index of this repository.\n\n__PIPELINE_TOOLS__\nCheck each candidate term with CodeGraph (query a symbol, explore terms). A candidate term that resolves to NOTHING in this index is noise and\nbelongs in the blacklist, however unusual the word looks. Do not assert that a term is\nmeaningful — check it.\n\nWHY THIS MATTERS HERE: the list you return feeds a BM25/IDF ranker. That ranker DEMOTES\nterms which are common in the corpus and AMPLIFIES terms which are rare. So a rare,\nmeaningless token — a bracketed brand tag, a ticket label, a person's name — is not\ndiluted, it is promoted to a top discriminator and drags the search away from the real\ncode. Rare-and-meaningless is the failure mode you exist to prevent; do not mistake\nrarity for signal.\n",
+  "description": "Told to the guard-vocabulary agent only when a CodeGraph index exists to verify terms against.",
+  "id": "guard-vocabulary-codegraph",
+  "placeholders": [
+    "__PIPELINE_TOOLS__"
+  ],
+  "version": 1,
+  "seams": [
+    "guard-vocabulary"
+  ]
+}

package/orchestrations/prompts/templates/guard-vocabulary-documentation.json

@@ -0,0 +1,21 @@
+{
+  "$why": [
+    "A FRAGMENT of guard-vocabulary, 2026-08-15. Present only when documentation was fetched.",
+    "",
+    "It is NOT just a heading around the quotes: it carries the rule that a vendor-published",
+    "name describing OBSERVABLE behaviour must not be flagged, while the same name asserting",
+    "the shape of an internal object still must. Templating the heading alone silently dropped",
+    "those five lines, and the byte check caught it — a guard that had lost the distinction",
+    "would have started flagging every documented name it saw."
+  ],
+  "body": "DOCUMENTATION LINKED ON THIS TICKET (fetched and quoted verbatim — the vendor's published contract):\n__DOC_BLOCK__\n\nA name that appears above is something the VENDOR publishes, not something this team chose.\nDo NOT flag it when a statement uses it to describe OBSERVABLE behaviour — what a user or a\ntest can see happen. DO still flag it when the statement asserts the shape or contents of an\nINTERNAL object, argument or call, even if the name itself is documented: that is an\nimplementation detail wearing a published name.\n\n",
+  "description": "Told to the guard-vocabulary agent only when the ticket carried documentation.",
+  "id": "guard-vocabulary-documentation",
+  "placeholders": [
+    "__DOC_BLOCK__"
+  ],
+  "version": 1,
+  "seams": [
+    "guard-vocabulary"
+  ]
+}

package/orchestrations/prompts/templates/guard-vocabulary.json

@@ -0,0 +1,34 @@
+{
+  "$why": [
+    "Moved out of spec-mode-runner.js deriveGuardVocabulary on 2026-08-15 (4 of 20).",
+    "",
+    "The terms this returns feed a BM25/IDF ranker, so the prompt decides what the search",
+    "amplifies and what it demotes. It carries FOUR conditional sections \u2014 persona,",
+    "documentation, evidence and the CodeGraph verify block \u2014 each assembled by the caller and",
+    "arriving whole or empty. A template that branches is a program."
+  ],
+  "body": "GUARD SEAM: __SEAM__\n\nTHE RULE THIS GUARD ENFORCES:\n__RULE__\n\nTHE STATEMENTS THE GUARD WILL CHECK:\n__STATEMENT_LIST__\n\nDECLARED MANIFEST (the files this story says it will touch):\n__MANIFEST__\n\n__DOC_SECTION__CODE EVIDENCE (real findings from this repository \u2014 ground truth; derive from these, not from your own knowledge of any library):\n__EVIDENCE__\n\nSTORY CONTEXT:\nTitle: __STORY_TITLE__\nDescription: __STORY_DESCRIPTION__\n__CODEGRAPH_SECTION__",
+  "description": "Derive the vocabulary a guard uses, verified against the repository index.",
+  "id": "guard-vocabulary",
+  "placeholders": [
+    "__CODEGRAPH_SECTION__",
+    "__DOC_SECTION__",
+    "__EVIDENCE__",
+    "__MANIFEST__",
+    "__RULE__",
+    "__SEAM__",
+    "__STATEMENT_LIST__",
+    "__STORY_DESCRIPTION__",
+    "__STORY_TITLE__"
+  ],
+  "version": 1,
+  "seams": [
+    "guard-vocabulary"
+  ],
+  "mayBeEmpty": [
+    "__CODEGRAPH_SECTION__",
+    "__DOC_SECTION__"
+  ],
+  "$mayBeEmptyWhy": "Both are REAL absent states, and production passes '' for them: spec-mode-runner supplies __CODEGRAPH_SECTION__ only when a codegraph tool AND a repo path are present, and __DOC_SECTION__ only when the story references documents. Without this declaration the prompt layer refuses to render for any project that has not provisioned the codegraph plugin \u2014 deriveGuardVocabulary then returns null, which its own callers must read as 'the guard could not be armed'. So the guard silently disarmed itself on exactly the projects least likely to notice. Unlike a brief or a tool grant, an absent section here reads correctly as absent.",
+  "$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/hybrid-prephase-coordinator.json

@@ -0,0 +1,16 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-16."
+  ],
+  "description": "Coordinates the hybrid pre-phase pass for one phase.",
+  "id": "hybrid-prephase-coordinator",
+  "seams": [
+    "cpa-inference"
+  ],
+  "placeholders": [
+    "__PHASE_ID__",
+    "__PRD_REL__"
+  ],
+  "version": 1,
+  "body": "You are the coordination agent running in HYBRID PRE-PHASE mode for phase: __PHASE_ID__.\n\n## Task\n1. Read __PRD_REL__ and locate all stories in implementationOrder[\"__PHASE_ID__\"].\n2. Identify cross-lane dependencies between main, primary, and independent agent groups.\n3. Flag any stories where estimatedHours >= 6 or dependencies count >= 2 — these require plan mode.\n4. For each cross-lane dependency or plan-mode story, append a JSON message to orchestrations/logs/agent-messages.jsonl.\n   Use this schema (one compact JSON line per message):\n   {\"id\":\"coord_<storyid>_<epoch>\",\"timestamp\":\"<ISO8601>\",\"from_agent\":\"coordination-agent\",\"to_agent\":\"<agentRole>\",\"story_id\":\"<id>\",\"phase_id\":\"__PHASE_ID__\",\"message_type\":\"<handoff|plan_required|risk>\",\"priority\":\"normal\",\"subject\":\"<subject>\",\"body\":\"<body>\",\"status\":\"new\"}\n5. Post a final {\"message_type\":\"phase_ready\",\"to_agent\":\"orchestrator\",\"phase_id\":\"__PHASE_ID__\",...} message when complete.\n6. Use: (flock -w 10 9 >> orchestrations/logs/agent-messages.jsonl; printf '%s\\n' '<json>' >&9) 9>>orchestrations/logs/agent-messages.jsonl for atomic writes.\n7. Write a summary of actions to orchestrations/logs/hybrid-coord-__PHASE_ID__.log.\n\n## Constraints\n- Do NOT modify source code or prd.json stories.\n- Only write to orchestrations/logs/agent-messages.jsonl and orchestrations/logs/hybrid-coord-__PHASE_ID__.log."
+}

package/orchestrations/prompts/templates/inference-ladder-coordinator.json

@@ -0,0 +1,27 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-16.",
+    "",
+    "The decision this prompt makes is which model a retry runs on and whether the prompt is",
+    "amended before it — so its wording directly governs escalation. It had no reviewable home,",
+    "and a wording change to it meant editing and shipping a 12,000-line shell script."
+  ],
+  "description": "Decides whether a failed story retry should escalate to a stronger model, and whether a prompt amendment would help.",
+  "id": "inference-ladder-coordinator",
+  "seams": [
+    "cpa-inference"
+  ],
+  "placeholders": [
+    "__PRIOR_FAILURE_SUMMARY__",
+    "__RESULT_TEXT__",
+    "__TEST_FAILURE_SNIPPET__",
+    "__LOG_TAIL__",
+    "__COORDINATOR_FAILURE_CLASS__",
+    "__CURRENT_MODEL__",
+    "__TARGET_MODEL__",
+    "__STORY_TITLE__",
+    "__STORY_ID__"
+  ],
+  "version": 1,
+  "body": "You are the inference ladder coordinator. A story implementation just failed. You must decide whether to escalate to a stronger model for the retry, and whether a targeted prompt amendment would help.\n\n## Story\n- ID: __STORY_ID__\n- Title: __STORY_TITLE__\n- Current model: __CURRENT_MODEL__\n- Proposed escalation model: __TARGET_MODEL__\n- Failure class (preliminary): __COORDINATOR_FAILURE_CLASS__\n\n## Failure Evidence (last attempt result)\n__RESULT_TEXT__\n\n## Log Tail\n__LOG_TAIL__\n\n## Test Failure Output (if tests ran)\n__TEST_FAILURE_SNIPPET__\n\n## Cross-Run History\n__PRIOR_FAILURE_SUMMARY__\n\n## Your Assessment\nAnswer ONLY with a single-line JSON object (no markdown, no prose):\n{\"escalate\":\"yes|no\",\"failure_class\":\"env|capability|quality|unknown\",\"prompt_amendment\":\"<targeted instruction to add to retry prompt, or empty string>\",\"rationale\":\"<one sentence>\"}\n\nRules:\n- escalate \"yes\" ONLY when the failure is due to model capability limits (max iterations, context window, weak reasoning, missing knowledge)\n- escalate \"no\" when the failure is environmental (missing API key, binary crash, file permission) — a stronger model won't fix it\n- escalate \"no\" when the failure is a prompt misunderstanding — suggest a prompt_amendment instead\n- prompt_amendment should be a concrete instruction (e.g., \"Do not import from node-fetch — use native global fetch only\") not a vague suggestion\n- Keep rationale under 15 words"
+}

package/orchestrations/prompts/templates/kb-enforcement-synthesis.json

@@ -0,0 +1,28 @@
+{
+  "$why": [
+    "Moved out of lib/kb-synthesizer.js on 2026-08-16.",
+    "",
+    "The schema arrived here as constraintSchema().slice(0, 4000) -- a truncation, of the one",
+    "value the model is told its answer is VALIDATED against. Cutting a JSON schema at a byte",
+    "offset leaves a fragment that is not a schema at all, and the failure mode is an answer",
+    "rejected for not matching rules the model was never shown. The cut is gone; the schema is",
+    "supplied whole, per the standing no-truncation rule.",
+    "",
+    "2026-08-17: named tsc/vitest as the adjudicators of a deterministic gate. The KIND of check is the point; the tools belong to the codeline."
+  ],
+  "description": "Chooses the enforcement that prevents a repeated agent failure from recurring.",
+  "id": "kb-enforcement-synthesis",
+  "seams": [
+    "kb-synthesizer"
+  ],
+  "$whySeam": "Executed by lib/kb-synthesizer.js under EPAM_AGENT_NAME kb-synthesizer, the registry seam whose template this is. It was declared for impl-failure-analyst — the seam whose repeated failure it prevents, not the one that runs it — so a rehearsal answered it under the wrong seam (2026-09-14).",
+  "placeholders": [
+    "__EPISODE_COUNT__",
+    "__AGENT_ROLE__",
+    "__SIGNATURE__",
+    "__EVIDENCE__",
+    "__CONSTRAINT_SCHEMA__"
+  ],
+  "version": 1,
+  "body": "You are deciding how to PREVENT a repeated agent failure, not how to describe it.\n\nThe same failure signature has now occurred __EPISODE_COUNT__ times for agent role\n\"__AGENT_ROLE__\". Below is the evidence.\n\nFAILURE SIGNATURE: __SIGNATURE__\nAGENT ROLE:        __AGENT_ROLE__\n\nEVIDENCE (__EPISODE_COUNT__ occurrences):\n__EVIDENCE__\n\nYour reply becomes an ENFORCED CONSTRAINT, not advice an agent may read and ignore.\nIt must therefore bind to a real mechanism. There are exactly six:\n\n  gate        a deterministic check adjudicated by this codeline's own type check and test run, failing closed\n              -> {\"kind\":\"gate\",\"check\":\"<check-id>\"}\n  param       a NON-BUDGET invocation field the agent cannot exceed\n              -> {\"kind\":\"param\",\"name\":\"EPAM_REASONING_EFFORT\",\"value\":\"high\"}\n  tool_scope  narrow what the agent may write or which tools it may call\n              -> {\"kind\":\"tool_scope\",\"allowed_write_paths\":\"src/x.ts\"}\n  pre_exec_block  refuse a command before it runs (literal substring)\n              -> {\"kind\":\"pre_exec_block\",\"pattern\":\"--no-verify\"}\n  response_schema bind the agent's output shape so it cannot reply free-form\n              -> {\"kind\":\"response_schema\",\"name\":\"verdict\",\"schema\":{...}}\n  effort_tier RAISE the story's effort tier when the agent ran out of ROOM\n              -> {\"kind\":\"effort_tier\",\"tier\":\"high\"}\n\nRESOURCE BUDGETS — READ THIS BEFORE PROPOSING ONE.\nYou may NOT set iteration counts, token limits or timeouts as a \"param\"\n(EPAM_MAX_ITERATIONS, EPAM_MAX_OUTPUT_TOKENS, *_TIMEOUT_SECS ...). Those are\nassigned by a pipeline you cannot see the whole of:\n\n    CPA estimates the story's hours\n      -> <=2h = low | <=6h = medium | >6h = high\n      -> low = 6 iterations | medium = 10 | high = 15   (fixed table)\n\nIf an agent genuinely ran out of ROOM, say so in the only vocabulary that plugs\ninto that pipeline: raise the tier with \"effort_tier\". It is applied UPGRADE-ONLY,\nso a lower tier is ignored. Never propose a number — you do not have the estimate,\nthe thresholds or the table, and a number invented from one failure will be wrong.\n\nIf none of the six can prevent this failure, reply exactly: NO_CONSTRAINT\nThat is a valid and useful answer. Inventing a mechanism that does not exist is not.\n\nOutput ONLY a JSON object with these two fields, no prose and no fences:\n{\"enforcement\": <one of the six shapes above>, \"reason\": \"<why this prevents a recurrence, under 25 words>\"}\n\nThe enforcement object is validated against this schema; anything else is discarded:\n__CONSTRAINT_SCHEMA__\n"
+}

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

@@ -0,0 +1,20 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-16. Same shape as lint-finding-analyst:",
+    "the current ACs and the role instructions were both computed by shell pipelines inside the",
+    "heredoc, so the remediator could be asked to extend criteria it had not been shown."
+  ],
+  "description": "Adds acceptance criteria to the story a lint failure was mapped to, so the failure cannot recur.",
+  "id": "lint-ac-remediator",
+  "seams": [
+    "ac-elaboration"
+  ],
+  "placeholders": [
+    "__STORY_ID__",
+    "__FINDING__",
+    "__CURRENT_ACS__",
+    "__PROFILE__"
+  ],
+  "version": 1,
+  "body": "You are the story-ac-remediator. A lint gate failure was mapped to story '__STORY_ID__'.\n\n## Finding\n__FINDING__\n\n## Current story ACs\n__CURRENT_ACS__\n\n## Agent Profile\n__PROFILE__\n\nAdd 1-2 ACs to story '__STORY_ID__' that would prevent this lint failure. Output JSON only:\n{\"story_id\":\"__STORY_ID__\",\"new_acs\":[\"<ac text>\"],\"rationale\":\"<why>\"}"
+}

package/orchestrations/prompts/templates/lint-fixer.json

@@ -0,0 +1,19 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-16.",
+    "",
+    "The lint-fixer edits files in place to a minimal, idiomatic change. Its wording is what keeps a style fix from turning into a refactor -- extracting a repeated literal into a constant is fine, changing what is asserted is not."
+  ],
+  "description": "Fixes code-style findings a linter reported, minimally and in place.",
+  "seams": [
+    "story-writer"
+  ],
+  "id": "lint-fixer",
+  "version": 1,
+  "body": "You are fixing code-style findings a linter reported on files THIS RUN just wrote.\n\n## Findings to fix (and nothing else)\n__LF_FINDINGS__\n\n## Rules\n1. Fix ONLY these findings, ONLY in these files. Do not refactor anything else.\n2. Do NOT weaken any test. Assertions, expected values and the scenario under\n   test must be preserved EXACTLY — a test here is the only executable proof the\n   bug is fixed, and a test that no longer proves it is far worse than a lint\n   warning. Extracting a repeated literal into a constant is fine; changing what\n   is asserted is not.\n3. Keep the change minimal and idiomatic for this repository.\n4. Edit the files in place with your write tool. Do not create new files.\n\nFiles: __LF_FILES__\nProject root: __PROJECT_ROOT__",
+  "placeholders": [
+    "__LF_FINDINGS__",
+    "__PROJECT_ROOT__",
+    "__LF_FILES__"
+  ]
+}

package/orchestrations/prompts/templates/manifest-analysis.json

@@ -0,0 +1,13 @@
+{
+  "$why": [
+    "Moved out of src/scaffold/prompts.ts on 2026-08-15 alongside agent-proposal, same reason.",
+    "Declares no placeholders: the manifest arrives as the turn content, not by substitution."
+  ],
+  "body": "You are a senior project analyst. You will receive a project manifest written in free-form markdown.\n\nYour job:\n1. Summarise the project in 2-3 sentences.\n2. Infer a short project name (kebab-case, e.g. \"todolist-app\").\n3. Suggest an uppercase story ID prefix (3-5 chars, e.g. \"TODO\").\n4. Extract the tech stack as a string array.\n5. Generate 3-7 clarifying questions that would help generate better user stories. Focus on ambiguities, missing acceptance criteria, unclear scope boundaries, deployment targets, and user personas.\n\nRespond with ONLY valid JSON matching this schema (no markdown fences):\n{\n  \"summary\": \"<string>\",\n  \"projectName\": \"<string>\",\n  \"suggestedPrefix\": \"<string>\",\n  \"techStack\": [\"<string>\"],\n  \"questions\": [\"<string>\"]\n}",
+  "description": "Phase A of scaffolding: summarise a project manifest and raise clarifying questions.",
+  "id": "manifest-analysis",
+  "placeholders": [],
+  "version": 1,
+  "seams": [],
+  "consumer": "engine"
+}

package/orchestrations/prompts/templates/mint-existing-roster.json

@@ -0,0 +1,25 @@
+{
+  "$why": [
+    "Added 2026-08-24, after the second a live ticket run.",
+    "",
+    "The mint was told which roles already exist by FIXED_AGENT_ROLES — a hardcoded list of 21",
+    "names in src/scaffold/prdTypes.ts — while the canonical roster holds 57 agents. So 39",
+    "canonical agents were invisible to the proposer, including test-engineer.",
+    "",
+    "That is not academic. On 2026-08-23 the roster reviewer raised a blocking finding that the",
+    "implementer's brief 'defers test ownership to a dedicated test agent, but no test agent was",
+    "minted in this roster' — while a canonical test-engineer existed the whole time and the mint",
+    "had never been shown it. A proposer that cannot see the roster it is adding to either",
+    "duplicates a role under a new name or reports a gap that is already filled.",
+    "",
+    "The list is READ FROM THE ROSTER at call time, never restated here: a hardcoded roster",
+    "drifts from the real one the moment either changes, which is the defect this replaces."
+  ],
+  "description": "Names the agents that already exist, so the mint proposes what is missing rather than what is already there.",
+  "id": "mint-existing-roster",
+  "authority": "template",
+  "seams": ["agent-mint"],
+  "body": "THESE AGENTS ALREADY EXIST AND WILL BE PART OF THIS TEAM. Do NOT propose any of them\nagain, and do not propose a role whose remit overlaps one of them under a different name.\nPropose only what is genuinely missing:\n\n__ROSTER_LIST__\n\nIf the work needs something one of these already covers, that need is MET — say nothing about\nit. A gap you report that one of these agents already fills is a false gap, and it costs the\nteam a role it does not need.\n",
+  "placeholders": ["__ROSTER_LIST__"],
+  "version": 1
+}

package/orchestrations/prompts/templates/new-dependency-directive.json

@@ -0,0 +1,28 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-19, and corrected in the same move.",
+    "",
+    "The shell string it replaces told the writer: 'import it directly and continue -- missing imports are detected and installed automatically after your change; this does not need your permission or a separate step.' A live brownfield run followed that instruction exactly. Nothing installed anything: the automatic path fires only when the PROJECT declares autoInstall, and this one does not. The manifest gained a dependency, the lockfile never moved, and the branch cannot be installed from a clean checkout -- while the type check, the tests and the build all passed against a vendor directory left over from an earlier run.",
+    "",
+    "The directive exists because agents used to STALL, asking permission for a dependency in an unattended run. That problem is real, so this still says 'do not stop to ask'. What changed is the second half: the writer is told to run the install itself, and told why -- so the manifest and the lockfile are written together by the one tool that keeps them consistent.",
+    "",
+    "It names no package manager, no manifest and no lockfile. All three are values, resolved from lib/ecosystem-registry.js for whichever codeline this is.",
+    "",
+    "SPLIT ON 2026-08-19, same day: the first version required a lockfile before it would render anything, which silently withdrew the anti-stall instruction from every codeline that has no lockfile -- reintroducing the exact stall this directive was created to stop. The lockfile half is now its own block, rendered only when there is a lockfile to keep in step."
+  ],
+  "description": "Tells the writer how to add a dependency this project does not yet declare.",
+  "seams": [
+    "story-writer"
+  ],
+  "id": "new-dependency-directive",
+  "version": 1,
+  "placeholders": [
+    "__INSTALL_COMMAND__",
+    "__LOCKFILE_NOTE__"
+  ],
+  "body": "## Adding a New Dependency\nIf the change genuinely requires a package this project does not yet declare, add it and continue — do not stop to ask whether this is allowed, and do not look for a worse solution that avoids it.\n\nAdd it by running:\n\n    __INSTALL_COMMAND__\n__LOCKFILE_NOTE__",
+  "mayBeEmpty": [
+    "__LOCKFILE_NOTE__"
+  ],
+  "$mayBeEmptyWhy": "__LOCKFILE_NOTE__ is the note about this ecosystem's lockfile, and there is not always one to give. Its caller in claude.sh sets it to '' and continues with the warning 'the writer gets no lockfile note' — the author's own handled branch, not a failed lookup. Undeclared, the renderer refused the whole directive and the writer was refused with it: on 2026-08-28 mock3 reached the writer for the first time, created the story branch bugfix/AI-MOCK3-2, and stopped there."
+}

package/orchestrations/prompts/templates/new-dependency-lockfile-note.json

@@ -0,0 +1,20 @@
+{
+  "$why": [
+    "The half of the new-dependency directive that only applies to a codeline carrying a lockfile.",
+    "",
+    "A live brownfield run hand-edited package.json and never ran an install, so package-lock.json did not move. Every check passed against a vendor directory left over from an earlier run, and the branch cannot be installed from a clean checkout.",
+    "",
+    "Separate from the parent so that a codeline WITHOUT a lockfile still receives the directive's other half -- the instruction not to stall asking permission, which is why the directive exists at all."
+  ],
+  "description": "Tells the writer to keep the manifest and the lockfile in step by installing rather than hand-editing.",
+  "seams": [
+    "story-writer"
+  ],
+  "id": "new-dependency-lockfile-note",
+  "version": 1,
+  "placeholders": [
+    "__MANIFEST_FILE__",
+    "__LOCKFILE__"
+  ],
+  "body": "\nRun that command rather than editing __MANIFEST_FILE__ by hand. __MANIFEST_FILE__ states an intent; __LOCKFILE__ is the only record of what a clean checkout actually installs, and the command above writes both together. A hand-edited manifest leaves __LOCKFILE__ untouched — your import will still resolve here, because the package may already be present from earlier work, so the type check and the tests will pass and the change will still be broken for everyone else. A deterministic check verifies this and will reject the story.\n\nDo not edit __LOCKFILE__ yourself.\n"
+}

package/orchestrations/prompts/templates/phase-assessment-header.json

@@ -0,0 +1,19 @@
+{
+  "$why": [
+    "Moved out of run-agent-orchestration.sh on 2026-08-16.",
+    "",
+    "The phase header prepended to the skill assessment: which phase is being assessed and what Step 0.5 is permitted to change. That permission boundary is the whole gate -- an assessment allowed to rewrite anything is not an assessment."
+  ],
+  "description": "Frames a skill assessment with its phase and the changes it is permitted to make.",
+  "seams": [
+    "phase-assessment"
+  ],
+  "id": "phase-assessment-header",
+  "version": 1,
+  "body": "__ASSESSMENT_PROMPT__\n\n## Phase: __PHASE_ID__\n\nRead __PRD_REL__ implementationOrder[\"__PHASE_ID__\"] for the story list, then proceed with the analysis above.",
+  "placeholders": [
+    "__ASSESSMENT_PROMPT__",
+    "__PHASE_ID__",
+    "__PRD_REL__"
+  ]
+}

package/orchestrations/prompts/templates/pipeline-tools-command.json

@@ -0,0 +1,13 @@
+{
+  "$why": [
+    "THE PIPELINE'S TOOLS, ON A SET WHERE THE AGENT RUNS THEM THROUGH ITS SHELL.",
+    "Each is named by a variable from config/pipeline-tool-commands.json, which the hub exports — the",
+    "agent's shell resolves it, so no local path is written into the prompt (operator, 2026-10-01).",
+    "Chosen by lib/pipeline-tools.js; the counterpart is pipeline-tools-hosted."
+  ],
+  "id": "pipeline-tools-command",
+  "description": "Tells an agent which pipeline tools it has, on a set where it runs them through its shell.",
+  "version": 1,
+  "placeholders": [],
+  "body": "YOUR TOOLS — run each with your shell tool exactly as written (the variables are already set in your environment, and you work at the repository root):\n  bash \"$EPAM_CODEGRAPH_TOOL\" explore <domain nouns>\n  bash \"$EPAM_CODEGRAPH_TOOL\" query <SymbolName>      # exact definition + signature + import path\n  bash \"$EPAM_CODEGRAPH_TOOL\" callers <SymbolName>\n  bash \"$EPAM_CODEGRAPH_TOOL\" callees <SymbolName>\n  bash \"$EPAM_CODEGRAPH_TOOL\" show <file> [startLine] [endLine]\n  bash \"$EPAM_SEARCH_TOOL\" --string \"<exact symbol>\" [--glob \"*.ts\"]\n  bash \"$EPAM_SEARCH_TOOL\" --file \"<part of a filename>\"\n  bash \"$EPAM_PACKAGE_SYMBOL_TOOL\" \"<package name>\" \"<method or function name>\"   # a third-party symbol's real declared shape and documented usage\n"
+}

package/orchestrations/prompts/templates/pipeline-tools-hosted.json

@@ -0,0 +1,12 @@
+{
+  "$why": [
+    "THE PIPELINE'S TOOLS, ON A SET THAT ATTACHES THEM TO THE AGENT (its runner declares hostedToolPlugins).",
+    "Chosen by lib/pipeline-tools.js; the counterpart is pipeline-tools-command. No path: the tools are",
+    "attached, and their schemas say the rest (operator, 2026-10-01: relative paths only)."
+  ],
+  "id": "pipeline-tools-hosted",
+  "description": "Tells an agent which pipeline tools it has, on a set that hosts them as tools.",
+  "version": 1,
+  "placeholders": [],
+  "body": "YOUR TOOLS — they are attached to you; call them directly (there are no scripts to run):\n  codegraph_query — mode \"explore\" with terms \"<domain nouns>\"; mode \"query\", \"callers\" or \"callees\" with symbol \"<SymbolName>\"; mode \"show\" with file \"<file>\" and optional startLine/endLine. When more than one codeline is in scope, name the codeline.\n  your search tool — find an exact symbol, or a file by part of its name, across the working tree.\n  resolve_package_symbol — packageName \"<package name>\", symbol \"<method or function name>\": a third-party symbol's real declared shape and the package's documented usage.\n"
+}

package/orchestrations/prompts/templates/plan-corrective.json

@@ -0,0 +1,21 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-16.",
+    "",
+    "RECOVERED 2026-08-20. The migration in b8e1e62 captured the WRONG LINES: this template's entire body was 69 characters of leaked shell — `_cp_vals=$(mktemp \"__TMPDIR__/plan-corrective-vals-XXXXXX.json` — and the prompt itself was lost. The renderer's strict placeholder check was the only thing standing between a model and a shell fragment presented as a corrective-plan instruction: __TMPDIR__ was never supplied, so it threw instead of sending it (live, run of 2026-08-19).",
+    "",
+    "The text below is the original, recovered verbatim from claude.sh at b8e1e62^."
+  ],
+  "description": "Asks the planner to correct a plan the reviewer rejected.",
+  "seams": [
+    "cpa-inference"
+  ],
+  "id": "plan-corrective",
+  "version": 1,
+  "body": "You previously produced this plan for story __STORY_ID__:\n\n__PLAN_TEXT__\n\nA review found it inconsistent with the real dependency contracts. Specific correction needed:\n__CORRECTIONS__\n\nProduce the CORRECTED numbered execution plan only — no prose, no code, same format as before.\n",
+  "placeholders": [
+    "__STORY_ID__",
+    "__PLAN_TEXT__",
+    "__CORRECTIONS__"
+  ]
+}

package/orchestrations/prompts/templates/plan-producer.json

@@ -0,0 +1,24 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-16. Produces a concrete implementation plan before any code is written.",
+    "",
+    "The declared-path classification was computed inside the prompt by a shell function, so what the planner was shown about its own output paths was decided by a command substitution nobody reviews.",
+    "",
+    "A second whole SECTION -- the dependency contracts -- was a conditional printf inside the prompt, so whether the planner saw the ground-truth import paths at all was decided by shell."
+  ],
+  "description": "Produces a concrete implementation plan for a story before any code is written.",
+  "seams": [
+    "cpa-inference"
+  ],
+  "id": "plan-producer",
+  "version": 1,
+  "body": "You are a planning agent. Produce a concise, numbered execution plan for the coding agent that will implement the following story. Output ONLY a numbered step list — no prose, no code.\n\nStory: __STORY_ID__ — __TITLE__\n\n## Output paths (EXACT — your plan MUST reference ONLY these paths for output steps, never invent alternatives)\n__DECLARED_PATHS__\n\n## Acceptance Criteria\n__AC__\n__DEPENDENCY_CONTRACTS__\n__CROSS_CODELINE_CONTRACT__\nProduce 5-10 numbered implementation steps. Your output steps MUST use the exact paths listed under 'Output paths' above, and must respect which of them already exist: a file listed as ALREADY EXIST is modified, never created. Be specific about function signatures and test requirements.",
+  "placeholders": [
+    "__DECLARED_PATHS__",
+    "__DEPENDENCY_CONTRACTS__",
+    "__CROSS_CODELINE_CONTRACT__",
+    "__STORY_ID__",
+    "__TITLE__",
+    "__AC__"
+  ]
+}

package/orchestrations/prompts/templates/plan-reviewer.json

@@ -0,0 +1,20 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-16. Reviews an implementation plan before it is acted on.",
+    "",
+    "A whole optional SECTION -- the declared output files -- was produced by a conditional printf inside the prompt, so whether the reviewer saw it at all was decided by shell rather than being visible in the prompt."
+  ],
+  "description": "Reviews an implementation plan before it is acted on.",
+  "seams": [
+    "cpa-gate"
+  ],
+  "id": "plan-reviewer",
+  "version": 1,
+  "body": "You are reviewing an implementation PLAN (not code) for story __STORY_ID__ before any code is written.\n\nCheck: (1) does the plan reference any file path, import path, exported class/function/type name that CONTRADICTS the dependency contracts? (2) do the plan's write/create steps use the EXACT declared output paths — not invented alternatives?\n\nYou have read-only tools available (list/search/read files, run read-only shell commands). If you are about to flag a mismatch based on something the plan claims about the filesystem or an installed package, VERIFY it with your tools first — do not assume. Your tool budget is small: check the ONE fact your verdict depends on, not the whole codebase.\n\nRespond with ONLY a JSON object, no markdown fences:\n{\"verdict\":\"ok\"} if the plan is consistent with both the contracts and the declared output paths, OR\n{\"verdict\":\"mismatch\",\"corrections\":\"<one paragraph telling the planning agent exactly what to fix, citing the real path from the contract or declared files list>\"}\n__DECLARED_OUTPUT_FILES__\n\n## Plan\n__PLAN_TEXT__\n\n## Dependency Contracts (ground truth)\n__DEPENDENCY_CONTRACTS__",
+  "placeholders": [
+    "__DECLARED_OUTPUT_FILES__",
+    "__DEPENDENCY_CONTRACTS__",
+    "__PLAN_TEXT__",
+    "__STORY_ID__"
+  ]
+}

package/orchestrations/prompts/templates/prd-change-reviewer-mode-rules.json

@@ -0,0 +1,28 @@
+{
+  "$why": [
+    "GREENFIELD JUDGES ACCEPTANCE CRITERIA. VERIFICATION CRITERIA ARE BROWNFIELD'S.",
+    "",
+    "The prd-change-reviewer persona states the VC-model rules — ACs immutable and never the spec",
+    "pass's output; reject when verificationCriteria is empty while the description names testable",
+    "behaviour. That is brownfield. On greenfield the spec pass REWRITES acceptance criteria and",
+    "verificationCriteria is never populated (enforceVerificationCriteria runs under",
+    "EPAM_BROWNFIELD=1 only), so the persona's rule rejected every non-split greenfield story three",
+    "times per agent — regintel 20260918T132928Z, core phase, model-independent.",
+    "",
+    "A fragment composed into the reviewer's profile value rather than an edit to the persona: the",
+    "persona is a canonical text whose provenance digest a settled roster carries, and a project's",
+    "own prd-change-reviewer-spec prompt is generated from its template and is not edited here.",
+    "Two bodies, selected by mode, so each reviewer is told the model it is judging under."
+  ],
+  "id": "prd-change-reviewer-mode-rules",
+  "description": "Which specification model the change reviewer judges under, by run mode.",
+  "version": 1,
+  "placeholders": [],
+  "seams": [
+    "prd-change-reviewer"
+  ],
+  "bodies": {
+    "greenfield": "MODE OVERRIDE — READ BEFORE APPLYING THE RULES ABOVE. This project runs the ACCEPTANCE-CRITERIA model (greenfield). Here the acceptance criteria ARE the spec pass's output: the spec pass MAY rewrite, add and sharpen acceptanceCriteria, and you judge the AFTER acceptanceCriteria — measurable, complete, consistent with the description, non-overlapping across split children. verificationCriteria is NOT produced on this project: an empty or absent verificationCriteria is NEVER a reason to reject, and the rule 'verificationCriteria is empty while the description names concrete testable behaviour' DOES NOT APPLY here. Likewise 'ACs are immutable / not the spec pass's output' does not apply: an AC edit is the change under review, not a violation.",
+    "brownfield": "This project runs the VERIFICATION-CRITERIA model (brownfield). The rules above apply as written: acceptance criteria come from upstream and are not the spec pass's output; the spec pass's deliverable is verificationCriteria."
+  }
+}

package/orchestrations/prompts/templates/prd-change-reviewer-spec.json

@@ -0,0 +1,33 @@
+{
+  "$why": [
+    "Moved out of spec-mode-runner.js reviewPrdChange on 2026-08-16.",
+    "",
+    "A SEPARATE template from prd-change-reviewer, which it closely resembles. The two have",
+    "DRIFTED and the difference is not cosmetic: claude.sh's version ends its tools paragraph",
+    "with \"a wrong rejection blocks a correct change and is worse than a slower correct one\",",
+    "and this one does not. This one also carries a split note the other has no concept of.",
+    "",
+    "Merging them on the resemblance would silently give one reviewer an instruction it has",
+    "never had, or take one away. Whether they SHOULD be one prompt is a decision about what",
+    "each reviewer is told, not a refactor."
+  ],
+  "body": "__MODE_RULES__\n\nSTORY: __STORY_ID__\nCHANGE TYPE: __CHANGE_TYPE__\n__SPLIT_NOTE__\nBEFORE:\n__BEFORE__\n\nAFTER:\n__AFTER__\n\nYou have read-only tools available (list/search/read files, run read-only shell commands). Several of your rejection rules (\"introduces a technology this project does not already use,\" \"TC fact cannot be verified by reading source code\") require checking a claim against the real manifests/config/source of THIS codeline — do not judge those from the before/after snapshots alone. Verify before rejecting on that basis. Your tool budget is small — check the ONE fact your verdict depends on, not the whole codebase.\n\nEmit ONLY: {\"verdict\":\"pass|fail\",\"issues\":[\"<issue1>\"],\"reason\":\"<15 words max>\"}",
+  "description": "Validate a proposed PRD change in the spec pass and return pass or fail.",
+  "id": "prd-change-reviewer-spec",
+  "placeholders": [
+    "__AFTER__",
+    "__BEFORE__",
+    "__CHANGE_TYPE__",
+    "__MODE_RULES__",
+    "__SPLIT_NOTE__",
+    "__STORY_ID__"
+  ],
+  "version": 1,
+  "seams": [
+    "prd-change-reviewer"
+  ],
+  "mayBeEmpty": [
+    "__SPLIT_NOTE__"
+  ],
+  "$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."
+}

package/orchestrations/prompts/templates/prd-change-reviewer.json

@@ -0,0 +1,27 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-15 (9 of 20). First migration in claude.sh, the file the",
+    "writer path runs through.",
+    "",
+    "The reviewer PROFILE is a value, not part of the template: it comes from profiles.json and",
+    "is the project-authority half of what this agent is told."
+  ],
+  "body": "__REVIEWER_PROFILE__\n\nSTORY: __STORY_ID__\nCHANGE TYPE: __CHANGE_TYPE__\n\nBEFORE:\n__BEFORE__\n\nAFTER:\n__AFTER__\n\nYou have read-only tools available (list/search/read files, run read-only shell commands). Several of your rejection rules (introduces a technology this project does not already use; TC fact cannot be verified by reading source code) require checking a claim against the real manifests/config/source of THIS codeline — do not judge those from the before/after excerpts alone. Verify before rejecting on that basis; a wrong rejection blocks a correct change and is worse than a slower correct one. Your tool budget is small — check the ONE fact your verdict depends on, not the whole codebase.\n\nEmit ONLY: {\"verdict\":\"pass|fail\",\"issues\":[\"<issue1>\"],\"reason\":\"<15 words max>\"}",
+  "description": "Validate a proposed PRD change against the codebase and pass or fail it.",
+  "id": "prd-change-reviewer",
+  "placeholders": [
+    "__AFTER__",
+    "__BEFORE__",
+    "__CHANGE_TYPE__",
+    "__REVIEWER_PROFILE__",
+    "__STORY_ID__"
+  ],
+  "version": 1,
+  "seams": [
+    "prd-change-reviewer"
+  ],
+  "mayBeEmpty": [
+    "__BEFORE__"
+  ],
+  "$mayBeEmptyWhy": "__BEFORE__ is empty when there is no before-state to compare: an ac_patch on a story whose acceptanceCriteria were absent is an ADDITION, and the caller passes \"\" deliberately. Undeclared, the reviewer could not render and the change went unreviewed (2026-08-28). __AFTER__ is NOT declared: an empty after-state means the change itself is missing, which is a defect the renderer must keep refusing."
+}

package/orchestrations/prompts/templates/prd-change-summarizer-text.json

@@ -0,0 +1,19 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-15 (10 of 20). The PRD-text variant — see the tool",
+    "variant for why these stayed two prompts."
+  ],
+  "body": "You are a PRD change summarizer. A __CHANGE_TYPE__ for story __STORY_ID__ was REJECTED by the change reviewer for these reasons:\n__ISSUES__\n\nORIGINAL TEXT:\n__REJECTED_TEXT__\n\nRewrite the text to fix ONLY the issues listed above, preserving the original actionable rule. Requirements: no reference to any specific story ID; start with an imperative verb (Use, Always, Never, Prefer, Avoid); under 200 characters; end on a complete sentence; no markdown, no headers, no commentary.\n\nEmit ONLY the corrected text — nothing else.",
+  "description": "Rewrite rejected PRD text to fix only the issues the reviewer raised, preserving the rule.",
+  "id": "prd-change-summarizer-text",
+  "placeholders": [
+    "__CHANGE_TYPE__",
+    "__ISSUES__",
+    "__REJECTED_TEXT__",
+    "__STORY_ID__"
+  ],
+  "version": 1,
+  "seams": [
+    "prd-change-summarizer"
+  ]
+}

package/orchestrations/prompts/templates/prd-change-summarizer-tool.json

@@ -0,0 +1,21 @@
+{
+  "$why": [
+    "Moved out of claude.sh on 2026-08-15 (10 of 20).",
+    "",
+    "The tool-script variant. It is a SEPARATE prompt from the text variant rather than one",
+    "prompt with a branch: they instruct differently and their output caps differ (4000 vs 400),",
+    "so folding them together would hide which one an agent actually received."
+  ],
+  "body": "You are a bash script reviewer-summarizer. A dynamic tool script for story __STORY_ID__ was REJECTED by the change reviewer for these reasons:\n__ISSUES__\n\nORIGINAL SCRIPT:\n__REJECTED_TEXT__\n\nRewrite the script to fix ONLY the issues listed above — a real bash bug (syntax error, subshell variable scoping, unquoted expansion, etc). Preserve the shebang line, the overall purpose, and every argument ($1, $2, ...) exactly as used. The script must remain idempotent (safe to run more than once).\n\nEmit ONLY the corrected script — no markdown fences, no commentary, no explanation.",
+  "description": "Rewrite a rejected dynamic tool script to fix only the issues the reviewer raised.",
+  "id": "prd-change-summarizer-tool",
+  "placeholders": [
+    "__ISSUES__",
+    "__REJECTED_TEXT__",
+    "__STORY_ID__"
+  ],
+  "version": 1,
+  "seams": [
+    "prd-change-summarizer"
+  ]
+}

package/orchestrations/prompts/templates/prd-configuration-block.json

@@ -0,0 +1,24 @@
+{
+  "$why": [
+    "Added 2026-09-17. regintel run 20260916T200108Z (resume on 2.0.45): the PRD declares",
+    "configuration.sourceRepoReadOnly \u2014 the read-only repository the scaffold story copies dial/,",
+    "docs/, manifest.md and requirements.txt from \u2014 and REGI-001a's description cites that key by",
+    "name. No prompt rendered the PRD's configuration object, so the writer was told to copy from a",
+    "repository it was never told the path of; it reported the blocker instead of fabricating files",
+    "(correctly), the deterministic check counted it a repeated violation, and the story failed.",
+    "",
+    "The block is DATA: the PRD's own configuration object, as JSON, with the $-prefixed comment",
+    "keys removed. The engine names no key; a project declares whatever its stories cite."
+  ],
+  "description": "The PRD-level configuration object, rendered into the writer's prompt so a story that cites a key by name has its value.",
+  "seams": [
+    "story-writer",
+    "spec-agent"
+  ],
+  "id": "prd-configuration-block",
+  "version": 1,
+  "body": "\n## Project Configuration (from the PRD \u2014 values a story may cite by key)\n```json\n__PRD_CONFIGURATION_JSON__\n```\n",
+  "placeholders": [
+    "__PRD_CONFIGURATION_JSON__"
+  ]
+}

package/orchestrations/prompts/templates/prd-generation.json

@@ -0,0 +1,16 @@
+{
+  "$why": [
+    "Moved out of src/scaffold/prompts.ts on 2026-08-15. The story-ID prefix and the role list are",
+    "per project, so both are placeholders — the template names no prefix and no role of its own."
+  ],
+  "body": "You are a senior product owner and technical architect. Generate a complete PRD (Product Requirements Document) as a JSON object.\n\nSTORY ID PREFIX: \"__STORY_ID_PREFIX__\"\nAVAILABLE AGENT ROLES: __AGENT_ROLES__\n\nGenerate a prd.json with:\n1. Project metadata (id, title, version \"1.0.0\", lastUpdated as today's date, project object with name/description/stack)\n2. User stories array — each story must have ALL these fields:\n   - id: \"__STORY_ID_PREFIX__-001\", \"__STORY_ID_PREFIX__-002\", etc.\n   - title: concise story title\n   - description: detailed description\n   - priority: \"critical\" | \"high\" | \"medium\" | \"low\"\n   - status: \"pending\"\n   - completed: false\n   - agentGroup: \"main\" | \"primary\" | \"independent\"\n   - agentRole: one of the available agent roles\n   - acceptanceCriteria: array of 2-5 testable criteria\n   - dependencies: array of story IDs this depends on (empty array if none)\n   - estimatedHours: number (0.5-8)\n   - technicalNotes: { files: string[], requiredSkills: string[] }\n   - storyType: \"implementation\" | \"review\" | \"health_check\"\n   - effort: \"low\" | \"medium\" | \"high\"\n3. implementationOrder: group story IDs into named phases (e.g. \"foundation\", \"core_features\", \"integration\", \"polish\")\n4. phasesConfig: for each phase, set orchestrationMode (\"bash\"), and a description\n\nRules:\n- Generate 10-30 stories depending on project complexity\n- Stories should be ordered by dependency — foundation first, then features, then integration\n- Every story must reference a valid agentRole from the available list\n- Dependencies must reference valid story IDs\n- Keep acceptance criteria specific and testable\n\nRespond with ONLY the valid JSON object (no markdown fences, no commentary).",
+  "description": "Phase C of scaffolding: generate a complete prd.json from the manifest and the minted roles.",
+  "id": "prd-generation",
+  "placeholders": [
+    "__AGENT_ROLES__",
+    "__STORY_ID_PREFIX__"
+  ],
+  "version": 1,
+  "seams": [],
+  "consumer": "engine"
+}