in2-agent-server 0.20260821.185429

package/dist/core/chapterInstructions.js

@@ -0,0 +1,473 @@
+// THE JUST-IN-TIME INSTRUCTION SURFACE — one chapter's expanded doctrine, returned AT that chapter.
+//
+// WHY THIS EXISTS AS A RETURN VALUE RATHER THAN AS MORE RESIDENT TEXT.
+//
+// The three channels that reach a supervisor all arrive at the START of a run and never again:
+// the MCP `instructions` (resident, and observed truncated at byte 2,050 — see
+// `supervisorContract.ts`), the bundled skill, and `supervisor-playbook.md` on disk. That shape
+// forces an unwinnable trade. Put the delivery rules in a resident channel and they compete for the
+// first 2 KB against the activation rules, which the run needs an hour earlier. Put them in the
+// playbook and the model reads them ninety minutes before it uses them, at the point in the run
+// when its context is emptiest and its attention is on intake.
+//
+// A TOOL RETURN HAS NEITHER PROBLEM. It costs nothing until it is called, it arrives at the moment
+// the instruction applies, and it lands in the context window at the position where the model is
+// about to act on it. That is why the doctrine diet and this tool are one design and not two: the
+// resident contract could only be cut to a skeleton because a just-in-time channel exists to carry
+// what was cut, and this channel is only affordable because the contract is a skeleton.
+//
+// WHAT BELONGS HERE, AND THE RULE THAT KEEPS IT FROM GROWING BACK INTO A SECOND PLAYBOOK.
+//
+// Only what the supervisor must have IN HAND to do THIS chapter and could get wrong without it.
+// Concretely: the order of operations no tool can see, the judgement calls no check makes, and the
+// live-caught lemmas whose cost is only payable once. NOT restatements of a tool description (they
+// arrive on the same connect, and truncation deletes the duplicate first), NOT restatements of a
+// refusal message (it arrives at the moment it fires, which is strictly better timing than this),
+// and NOT the operator-voice guide or the Configuration Item guide, both of which are files the
+// text POINTS at rather than inlines.
+//
+// The playbook remains the deep reference and the fallback for a run that never crosses a boundary.
+// Its step headings name their chapters (`supervisor-playbook.md`), so the two surfaces are
+// addressable in one vocabulary and per-step detail can migrate here without either becoming
+// unreadable.
+import { CHAPTERS } from "./phases.js";
+import { OPERATOR_VOICE_PATH, SUPERVISOR_PLAYBOOK_PATH } from "./paths.js";
+/**
+ * Written once, read on every boundary. Each entry is prose the model acts on directly, so it is
+ * addressed to the model in the second person and states its reasons — an instruction whose reason
+ * is missing is one a model will optimise away the first time it looks expensive.
+ */
+const BRIEFS = {
+    activation: {
+        headline: "Bind the session and the org",
+        progressLine: "Connecting to your Salesforce org and picking up the requirements you selected.",
+        instructions: [
+            "ACTIVATION — the session and the org become real, and nothing else happens yet.",
+            "",
+            "A pasted activation code is the whole start: `activate_session {code}` authenticates their org into",
+            "the sf CLI, binds it to the session, grants write authority to exactly that org, and imports the",
+            "requirements they picked in Campfire. Any other start is `create_session` then `import_requirements`.",
+            "An org that is not authenticated goes through `org_login`, a browser flow THEY complete — call it",
+            "again with the same alias until it reports CONNECTED.",
+            "",
+            "This batch is provider-bound: every step from here to close_batch uses the mcp__in2__ tools only,",
+            "whatever other Salesforce MCPs this client has connected.",
+            "",
+            "NEVER ask for a username, password or token, and never re-authenticate an org yourself when a",
+            "session dies. Salesforce auto-freezes an integration user on rapid retries, so a second attempt is",
+            "not free — stop, and tell the operator exactly what to run.",
+            "",
+            "CARRY THE sessionId, NOT AN ORG. Every org-touching tool derives its org from the session, bound and",
+            "verified when the session was created. `ALIAS_REPOINTED` means the alias moved to another org since",
+            "binding: card the operator, never work around it.",
+            "",
+            "SURFACE THE IDENTITY. `activate_session` reports which Salesforce USER the session acts as. Every",
+            "org change will be attributed to that user forever, so it goes to the operator in your first message,",
+            "not into your own notes.",
+            "",
+            "RELAY THE `Live progress:` URL exactly as `activate_session` returned it — it pins this session, and a",
+            "link you compose yourself would point the operator at another run. If the result carried no such line,",
+            "say nothing about a viewer.",
+            "",
+            "Advance to `intake` once the org is bound and the requirements are on disk."
+        ].join("\n")
+    },
+    intake: {
+        headline: "Read every requirement and form the batch model",
+        progressLine: "Reading through your requirements to understand what they add up to.",
+        instructions: [
+            "INTAKE — you read the whole batch yourself, before anything is delegated.",
+            "",
+            "This is codebase planning. Read ALL requirements first and form the BATCH MODEL: the shared",
+            "object(s), the cross-requirement dependency ladder (which requirements are an ordered chain and",
+            "which are independent), and any ambiguity that is only visible ACROSS requirements — three",
+            "requirements touching one object, two asking for contradictory sharing.",
+            "",
+            "READ INTENT ACROSS ALL THREE SURFACES of each requirement: the Solution Design Summary (the most",
+            "technical statement of HOW), the user story, and the acceptance criteria (what it is FOR). The",
+            "Summary is hand-written and sometimes asks for the impossible, or for what the other two contradict.",
+            "Work out what was INTENDED, propose the SMALLEST correction that achieves it, and recommend that.",
+            "Never refuse the requirement and never silently substitute your own reading. This is a CORRECTION",
+            "mechanism, not a licence to add — improving the design is the consultant's job.",
+            "",
+            "THEN GROUND ONCE. `project_org` across the scope you now know is touched. It is ground truth:",
+            "requirement-asserted API names are UNTRUSTED, and a component that already exists is a modify, never",
+            "a clobbering create. It also collects the org's traits (multi-currency, person accounts, call centre)",
+            "and a sample of precedent components on every run regardless of scope, which is exactly what a",
+            "greenfield batch needs most.",
+            "",
+            "YOU ARE THE ONLY ONE WHO CAN WIDEN THE PROJECTION. Analyzers READ it and cannot extend it, so",
+            "anything you fail to project is not missing to them — it is INVISIBLE, and they plan against a gap",
+            "they cannot see. Enumerate every metadata TYPE the batch touches, not just the objects: tabs, apps,",
+            "profiles, queues, groups, flows, approval processes, email templates, permission sets. Live-caught",
+            "2026-07-25: a batch projected as objects-plus-prefix left five types uncaptured and an analyzer had",
+            "to flag the blind spot itself.",
+            "",
+            "Advance to `partitioning` when you can state the batch model in a paragraph. If the batch is small",
+            "enough that you already hold it whole and will analyze it inline, you may advance straight past",
+            "`partitioning` and `parallel-analysis` to `clarification` — but read what that costs in the",
+            "partitioning brief before you decide."
+        ].join("\n")
+    },
+    partitioning: {
+        headline: "Write the brief and decide who analyzes what",
+        progressLine: "Planning how the work splits up before starting the detailed design.",
+        instructions: [
+            "PARTITIONING — the batch model becomes a session artifact, and the analyzer mapping is decided.",
+            "",
+            "WRITE THE BRIEF at `<sessionDir>/analysis/brief.md`: a shared preamble (the batch shape, the shared",
+            "objects, the dependency ladder, the decisions already in force) plus one delimited section per",
+            "requirement (its dependencies, its siblings, the trap it cannot see from its own text, and the",
+            "ownership of every shared component). Writing it ONCE and having N analyzers read it in parallel is",
+            "the speed mechanism: context that used to stream serially as output tokens into N Task prompts",
+            "becomes input tokens read concurrently. A measured 43-second start stagger across just four agents.",
+            "",
+            "RULES THE BRIEF LIVES BY:",
+            "- DECISIONS BIND; DESCRIPTIONS DO NOT. Carry decisions and POINTERS, never paraphrases of what an",
+            "  analyzer can read itself. Live-caught: a briefing described a flow guard using the wrong technique",
+            "  and the analyzer rightly mirrored the real artifact instead. A paraphrase is a bug vector.",
+            "- BINDING IS NOT UNCHALLENGEABLE. An analyzer never silently deviates from a brief decision — and",
+            "  never silently complies with one it can show is wrong either. The disagreement arrives as a",
+            "  BLOCKER citing evidence. That is the system working.",
+            "- AMENDMENTS ARE DATED APPENDS. When something changes mid-run you append rather than rewrite, so a",
+            "  re-dispatched analyzer reads the CURRENT brief and re-dispatch needs no prompt surgery.",
+            "",
+            "PRE-ASSIGN OWNERSHIP IN THE BRIEF — dedupe is a repair, not a plan. You already know the collisions",
+            "from reading the batch, so name the owner of every shared component (\"REQ-B: the object is REQ-A's —",
+            "record dependsOn, do NOT author it\") and fold facet-level asks into the creating owner's file. A",
+            "parent-object facet is an edit to the OBJECT and belongs in the object's own full-definition file,",
+            "not as its own components[] entry. Measured: with ownership stated up front, 15 analyzers produced",
+            "zero collisions and the wave plan ordered 24/24 first try. Without it, a create-owner/modify-owner",
+            "split on one field left 7 dependent components unordered.",
+            "",
+            "THE EARLY ROUND — ONE OPTIONAL CARD, HARD-GATED. Before fan-out you MAY ask one card of 1-3",
+            "questions. A question qualifies only if ALL THREE hold: it is visible from the requirement texts and",
+            "the projection alone; its answer unlocks or reshapes MULTIPLE requirements or the batch model itself;",
+            "and unanswered, analyzers must guess and their guesses could diverge. EACH QUESTION NAMES THE",
+            "REQUIREMENTS IT UNLOCKS — writing that clause is the test, and a question you cannot qualify that way",
+            "is self-evidently not an early question. Everything else waits for the consolidated round.",
+            "",
+            "SKIPPING THE FAN-OUT is a legitimate call on a small batch and it is much faster. Know exactly what",
+            "you give up: the analyzers' only durable output is `requirements/<extId>/plan.json`, and that file is",
+            "what decides WHICH REQUIREMENT EACH CONFIGURATION ITEM IS FILED AGAINST at writeback. Skip the",
+            "fan-out and that mapping exists only in your head — carry it forward explicitly by passing",
+            "`ownership: [{typeName, fullName, extId}]` to the Campfire tools, which refuse an unattributed plan.",
+            "Skip deliberately, never by drift.",
+            "",
+            "Advance to `parallel-analysis` when the brief is written and the mapping is decided."
+        ].join("\n")
+    },
+    "parallel-analysis": {
+        headline: "Fan out one analyzer per requirement",
+        progressLine: "Designing each requirement in detail, all of them at once.",
+        instructions: [
+            "PARALLEL ANALYSIS — every Task in ONE message, so wall clock is the slowest analyzer rather than",
+            "the sum of them.",
+            "",
+            "DELEGATION DEFAULTS TO 1:1, one analyzer per requirement, dispatched as",
+            "`subagent_type: \"plan-requirement\"`. That agent definition ships with the install and its `tools:`",
+            "frontmatter is a hard ALLOWLIST — the analyzer is handed only the five IN2 tools its skill permits",
+            "plus the file tools, so the ~21 it may not call are never loaded. If the agent type is not found,",
+            "STOP before any analysis — never dispatch a generic subagent in its place: it inherits every MCP",
+            "connected in this client, which un-scopes the one surface this allowlist exists to scope. The fix",
+            "rides on the server itself: every server START re-installs `~/.claude/agents` from the package, so",
+            "a missing definition means this session's start predates the copy — card the operator to start a",
+            "new conversation and re-paste their activation prompt (a fresh server start re-syncs the files;",
+            "nothing is lost), then `close_batch` and stop. If a fresh conversation STILL lacks the agent type,",
+            "the copy step itself is failing on this machine — card the operator to run `in2 setup` in a",
+            "terminal, then `close_batch` and stop.",
+            "",
+            "GROUP 2-3 ONTO ONE ANALYZER ONLY ON REAL COUPLING — one builds what another modifies or deletes, a",
+            "shared ordered ladder, a contradiction that needs one mind. NEVER topical similarity: with the brief",
+            "carrying the shared context there is no dispatch-economy reason left to group, and unearned grouping",
+            "just un-parallelizes the batch. A grouped analyzer still writes ONE plan.json PER requirement — that",
+            "artifact contract is inviolable, since wave planning, Configuration Item ownership and writeback all",
+            "read one plan.json per requirement. Partial-group failure is survivable by construction: each",
+            "finished plan.json persists as it is written, so you re-dispatch only what is missing.",
+            "",
+            "EACH TASK PROMPT IS A FIXED STUB, about forty tokens: read the plan-requirement skill (the tool list",
+            "names its path), you own <extId>, session <sessionId>, read your section(s) of the brief FIRST. Do",
+            "NOT paste cross-requirement context back into the prompts — that re-serialization is the dispatch",
+            "streaming this design removed.",
+            "",
+            "A PINSLEY-CLASS REQUIREMENT (one requirement the size of ten) splits BY DELIVERABLE AREA into",
+            "disjoint component sets, each fragment writing `plan.fragment-<n>.json` plus its own authored files.",
+            "YOU merge them into the one canonical `requirements/<extId>/plan.json`. `plan_waves` audits the",
+            "fragments before ordering anything and refuses an unmerged or doubly-claimed set by name",
+            "(`PLAN_FRAGMENTS_UNRESOLVED`, which spells out its own fix); what it cannot verify is the judgement",
+            "half — your summary and the blocker/assumption dedup are yours.",
+            "",
+            "Advance to `clarification` once every plan.json is on disk (and every fragment set is merged)."
+        ].join("\n")
+    },
+    clarification: {
+        headline: "Consolidate the plans and ask everything the batch genuinely raises",
+        progressLine: "Bringing the designs together and working out what needs a decision from you.",
+        instructions: [
+            "CLARIFICATION — a PHASE, not one tool call, and it happens BEFORE anything is applied.",
+            "",
+            "CONSOLIDATE FIRST. Read every plan.json. Dedupe by ownership: a component appearing in more than one",
+            "plan is created ONCE, owned by the requirement that most naturally creates it (usually the earliest",
+            "in the ladder), and the others merely DEPEND on it. Then `plan_waves {sessionId}` for the deploy",
+            "order — it reads the dependsOn the analyzers already recorded and returns the fewest waves the batch",
+            "allows.",
+            "",
+            "WHAT THE WAVE PLAN WILL TELL YOU, and what each answer means:",
+            "- A component this batch CHANGES AFTER CREATING IT is TWO entries — the same component,",
+            "  `intent: \"create\"` then `intent: \"update\"`, each naming its own `authoredFile`. Never one file",
+            "  plus a wave you assemble by hand: that path skips the ownership and drop checks entirely. The",
+            "  planner NAMES the split and never writes it; what the second state must CONTAIN is yours to author.",
+            "- A component the batch DELETES is an entry with `intent: \"delete\"` and no file. Planning orders it;",
+            "  nothing deletes it. That call is yours, and `dryRunOnly` goes first.",
+            "- \"not verifiable\" is answered with a `project_org` pass, never by deploying past it. A projection is",
+            "  a point-in-time read of a scope you chose, so absence from it is not evidence of absence from the org.",
+            "",
+            "THEN ASK EVERYTHING, BACK TO BACK. What is minimised is the OPERATOR'S ATTENTION WINDOW — they answer",
+            "in one focused stretch and then walk away while you execute — NOT your tool-call count. As many cards",
+            "as the batch honestly has; two readable cards beat one dense one. Never fold distinct ambiguities",
+            "together to hit a number: that pressure is exactly what turns a question into a guessed API name.",
+            "",
+            "A QUESTION WHOSE RECOMMENDATION YOU WOULD FOLLOW ANYWAY IS AN ASSUMPTION TO STATE, NOT A ROUND-TRIP",
+            "TO SPEND. Measured: 19 questions on one run, 18 answered with the recommendation, and operator wait",
+            "rose 9.2 minutes — cancelling out every second the parallel authoring had saved.",
+            "",
+            "THE TEST IS LIKELY DISSENT, NOT THE TEXT'S SILENCE. Ask yourself: might a reasonable operator",
+            "actually pick the other option? Business meaning, data risk, anything irreversible — yes, card it.",
+            "A recommendation any operator would confirm — display cosmetics (a formula that shows blank instead",
+            "of a meaningless number), a reading of a spec where both readings hold every real value, a platform",
+            "default the requirement does not contradict — is an assumption on the approval card. \"It deviates",
+            "from the literal text\" is NOT by itself a reason to ask: the approval card exists precisely so that",
+            "small, sensible deviations are DISCLOSED and consented to in one place. Live-caught 2026-08-05: a",
+            "run carded \"blank vs -46,700 days on an empty date\" and \"16 total digits vs 18\" — both answered",
+            "with the recommendation, both pure assumption material, two round-trips spent on questions whose",
+            "other option no operator would choose.",
+            "",
+            "`ask_operator` only RECORDS a card. Mirror every card through the native AskUserQuestion UI or the",
+            "operator never sees it and cannot answer. After answers: `record_operator_answers` FIRST, always —",
+            "it is the only record of what was actually chosen, and it closes the round so a resumed session can",
+            "tell an open card from a settled one. Then `resolve_blocker` when the answer is an edit you can make,",
+            "and a re-dispatch only when the reply changes WHICH components exist.",
+            "",
+            "Advance to `scope-approval` when every answer is recorded and every plan is reconciled."
+        ].join("\n")
+    },
+    "scope-approval": {
+        headline: "Show the full extent, then take one approval",
+        progressLine: "Putting the full plan in front of you for approval before anything changes in your org.",
+        instructions: [
+            "SCOPE AND APPROVAL — the last moment before the org changes, and the operator's only real gate.",
+            "",
+            "THE ORDERING IS FIXED: scope sheet -> approval card -> (in beta) the manual-time estimate card ->",
+            "first deploy. Ask the estimate card PLAINLY and NEVER EXPLAIN TO THE OPERATOR WHY IT COMES THERE —",
+            "the ordering answers a measurement problem that is ours, not theirs, and QA caught the tool reciting",
+            "that argument to the person it was measuring. The rule stays; the justification is not operator-facing.",
+            "",
+            `RENDER THE SCOPE SHEET AS ITS OWN MESSAGE, immediately before the card. Layouts and worked examples`,
+            `are in reference/templates.md beside ${SUPERVISOR_PLAYBOOK_PATH}. It is the full enumeration of what`,
+            "is about to happen in the org, grouped so the extent is visible at a glance, with every removal,",
+            "every deviation-from-as-written (each citing the answer that caused it) and every judgement call",
+            "flagged where it lands.",
+            "",
+            "THEN ONE APPROVAL CARD: the dependency-ordered plan, per-wave components, the assumptions in force",
+            "VERBATIM (approval is informed consent — an assumption paraphrased is an assumption not consented",
+            "to), the coverage routes, and the execution ask. One Recommended option: approve and execute.",
+            "",
+            "SAY WHAT VERIFICATION WILL NOT PROVE. `DIFF_VERIFIED` proves metadata SHAPE, never runtime behaviour.",
+            "Flows, validation rules and approval processes get a would-be-runtime-smoke note; content-file types",
+            "verify the meta, not the content bytes. An operator who thinks the harness proved behaviour has been",
+            "misled by omission.",
+            "",
+            "THE FIVE JUDGEMENT RULES THAT GOVERN WHAT YOU LET INTO THE BATCH, restated here because this is the",
+            "chapter where they bite:",
+            "- ADDITIONS: BENIGN IS FINE, OBLIGATION-CREATING IS NOT. An obvious additive detail on a brand-new",
+            "  component is welcome judgement. Forbidden is anything that CREATES OBLIGATIONS — a reference to a",
+            "  component that must then exist, a flag whose value implies further setup.",
+            "- NEVER PUT INVENTED SCOPE TO THE OPERATOR. If you added it and it is now a problem, remove it rather",
+            "  than escalating it as though the gap were theirs.",
+            "- NEVER MAKE SOMETHING REQUIRED THAT WAS NOT REQUESTED. A required field nobody asked for changes",
+            "  data entry for every user of that object forever. Absolute violation, however benign it looks.",
+            "- DELIVER IT, DO NOT DELEGATE IT. A Deployment Task hands work BACK to the consultant this system",
+            "  exists to save. If a human could do it in ten seconds, that is an argument for YOU doing it.",
+            "- READ INTENT ACROSS ALL THREE SURFACES, and propose the smallest correction rather than refusing.",
+            "",
+            "A deletion that removes something THIS BATCH CREATES goes on the card in the operator's own terms:",
+            "two requirements building what a third retires is a plan they should get to reconsider.",
+            "",
+            "Advance to `delivery` only after they approve. Change nothing in the org before that."
+        ].join("\n")
+    },
+    delivery: {
+        headline: "Deploy wave by wave with read-back proof",
+        progressLine: "Making the approved changes in your Salesforce org, in dependency order.",
+        instructions: [
+            "DELIVERY — one `direct_apply {sessionId, wave, waveComponents}` per wave, and nothing by hand.",
+            "",
+            "Pass that wave's component list straight from `plan_waves`. Assembly is a step INSIDE the call: the",
+            "analyzers' authored files are collected into `<session>/authored/<wave>/`, and that is what is linted,",
+            "validated and deployed in the same call, so there is no window in which the assembled tree and the",
+            "deployed tree can differ. `direct_lint` is the same assembly without the deploy.",
+            "",
+            "THE WAVE TREE IS A BUILD ARTIFACT, REBUILT EVERY CALL. A wave-specific fix goes in the requirement's",
+            "own file under `requirements/<extId>/authored/`. An edit made inside the wave tree is silently",
+            "overwritten rather than deployed, and nothing checks this.",
+            "",
+            "AUTHOR TO FILES, NOT INLINE XML. Source-format layout, since that is what the walk expects:",
+            "`objects/<Obj>/<Obj>.object-meta.xml`, `objects/<Obj>/fields/<F>.field-meta.xml`,",
+            "`flows/<F>.flow-meta.xml`, `email/<Folder>/<T>.email-meta.xml` plus its content file, and so on. Fix",
+            "the ONE bad file in place and call again. Re-sending full XML inline every call is dramatically",
+            "slower and the tree is what git history commits. Base64 static resources are the one exception.",
+            "",
+            "PASS `requirementIds` ON EVERY APPLY. The evidence bundle proves WHAT changed; only this says what it",
+            "was FOR, and it rides into the org's own history — which is where \"why does this field exist?\" gets",
+            "answered months from now by someone who was not on this run.",
+            "",
+            "READING THE VERDICTS:",
+            "- `DIFF_VERIFIED` is the target.",
+            "- `DELIVERED_WITH_DRIFT`: read `diff.json` and classify each drifted facet. Comparator noise",
+            "  (org-materialized `default:\"false\"`, array reorder, typed-value `{_,$}`, empty-array",
+            "  materialization, object key-order) is benign. RECONCILE WITH EVIDENCE, NOT ASSERTION: name the",
+            "  specific noise class AND cite the diff.json path per component. Never just say \"benign\" in chat.",
+            "- `REJECTED_BY_ORG`: fix from the verbatim `componentFailures` — the dry run is a direct, actionable",
+            "  error channel. Max 4 iterations, then STOP and card.",
+            "- `AMBIGUOUS_DELIVERY`: the deploy LANDED but the read-back failed. Re-`project_org` the scope; if the",
+            "  components are present and correctly shaped they are delivered, and the ambiguous origin plus the",
+            "  confirming projection is the evidence. Only if genuinely absent do you re-apply.",
+            "- A CONTENT REMOVED note means the component lost content between its pre- and post-image. Read the",
+            "  pre-image and fix the file rather than acking a drop you have not looked at.",
+            "",
+            "ORDERING TRAPS THAT COST A LIVE RUN:",
+            "- A facet a child component's shape DEPENDS ON goes in an earlier call or its own wave. Inside one",
+            "  apply the metadata deploy runs BEFORE the facet updates, so fields carrying `trackHistory` land",
+            "  while history is still off and the tracking does not take.",
+            "- Brownfield facet changes: a FULL `CustomObject` deploy first (it MERGES — an object deployed with",
+            "  its validationRules directory absent kept all three rules), `objectFacetUpdates` only as fallback.",
+            "- `dryRunOnly` before an irreversible wave. It checks deletes too, each with its own verdict. It does",
+            "  NOT prove a destructive package will land: those roll back WHOLE, so split the call rather than",
+            "  shipping a VALIDATED member beside a refused one. `objectFacetUpdates` have no practice mode at all.",
+            "- A ListView delete is a MANUAL SETUP TASK by default. \"Nothing references it\" is not evidence.",
+            "",
+            "NEVER RE-AUTH THE ORG YOURSELF. On `ORG_READ_FAILED` / `Session expired`: card the operator with the",
+            "fix (one line, re-auth from Campfire), then `close_batch {sessionId}`, then stop — IN THAT ORDER.",
+            "`close_batch` makes no org round-trip, so it works with every token dead; a run that stops at the",
+            "card reads as in-progress-forever and the waves that DID land are never reported. Rapid retries trip",
+            "Salesforce's integration-user auto-freeze, so never touch the token endpoint yourself.",
+            "",
+            "UNDOING A WAVE is `direct_rollback {sessionId, wave}`, never by hand and never by a sha. A custom",
+            "field deleted under 15 days ago is NOT a deploy: relay the tool's Setup undelete card, because an",
+            "undelete restores the field AND ITS DATA while a metadata re-create restores the definition, reports",
+            "success, and destroys every value in it.",
+            "",
+            "Advance to `review-results` when the last wave has a verdict — including when it has a bad one."
+        ].join("\n")
+    },
+    "review-results": {
+        headline: "Cross-check the claims, then review with the operator",
+        progressLine: "Checking what actually landed in your org against what was asked for.",
+        instructions: [
+            "REVIEW — cross-check every requirement's claims against verified org state BEFORE reporting.",
+            "",
+            "Drifted prose flowing into writeback publishes guarantees the org contradicts, and the writeback is",
+            "read by a ClickDeploy operator who was not on this run. So the order is: verify, then report, then",
+            "ask about writeback.",
+            "",
+            `COMPOSE THE REVIEW IN THE OPERATOR'S LANGUAGE, per ${OPERATOR_VOICE_PATH}. Read it before writing.`,
+            "- LEAD with what the independent org read proves and the exact configuration work still left to a",
+            "  person. Then a component-level table (Configuration | What happened in Salesforce). Verdicts arrive",
+            "  as `operatorSummary` phrasing, never as internal names.",
+            "- DO NOT CLAIM A CAMPFIRE COUNT YET. That belongs on the end-results page, after writeback has been",
+            "  independently read back.",
+            "- THEN \"Optional checks — about X minutes\" AS A CHECKBOX LIST. This section is REQUIRED. Verification",
+            "  proves metadata shape, never runtime behaviour, so map each requirement's metadata back to the",
+            "  human flow it implements and render concrete `- [ ]` steps: create a record of each type and compare",
+            "  picklist choices; trigger the validation rule with and without the bypass; assign the permission set",
+            "  (nothing in a batch assigns people); add queue/group members before expecting sharing rules to grant",
+            "  anything; send the email template from a record. Specific to THIS batch. Flag re-entry and",
+            "  duplicate-fire risk for record-triggered flows. This checklist is the deliverable's other half, not",
+            "  part of the manual-configuration count.",
+            "- CLOSE with \"Details for your technical team\": internal verdict names, drift classifications with",
+            "  their evidence citations, assumptions applied, coverage routes, session id and evidence locations.",
+            "  Everything above that section must be readable without it.",
+            "",
+            "\"I COULD NOT VERIFY THAT\" IS ONLY TRUE AFTER YOU LOOKED. Not having checked is not the same as not",
+            "being able to check, and reporting the second when you mean the first is a false statement about the",
+            "org.",
+            "",
+            "The review rides ABOVE the writeback question card, so the turn still ends in a card. Do NOT write to",
+            "Campfire yet — end by asking whether to.",
+            "",
+            "Advance to `writeback-close` once they answer that card, whichever way they answer it."
+        ].join("\n")
+    },
+    "writeback-close": {
+        headline: "Record the configuration items, then end the batch",
+        progressLine: "Recording the configuration items you delivered, and closing out the batch.",
+        instructions: [
+            "WRITEBACK AND CLOSE — the consultant org is REAL and SHARED, and this chapter ends the run.",
+            "",
+            "A WRITEBACK IS THE CONFIGURATION ITEMS. Not requirement notes, not Build Status, not Org",
+            "Deployed To. This program automates CONFIGURATION; deploying that configuration onward to other",
+            "environments is a separate process it does not perform, and a run that hands back manual work",
+            "has not finished a build. Do not call `update_campfire_requirements` — it is operator-directed",
+            "and outside this loop.",
+            "",
+            "THE ORDER IS THE PART NO TOOL ENFORCES:",
+            "1. `campfire_config_item_plan {sessionId}` FIRST. Its rows carry every observed delivery of each",
+            "   component and what the independent read-back actually confirmed. It returns the Configuration",
+            "   Item guide by absolute path in `guide`; that guide is the authority on manifest shape.",
+            "2. Resolve `ownershipGaps` and any ownership refusal WITH THE OPERATOR, never by guessing. The",
+            "   result reports `ownershipSource` — `plan` (computed) or `supervisor` (asserted by you) — and",
+            "   those carry different confidence, so say which it was.",
+            "3. THE WRITEBACK — `campfire_write_config_items {sessionId, ownership?}`, one call, the only",
+            "   Configuration Item writer there is. A correction is a re-derivation scoped with `waves`,",
+            "   never a hand-keyed row.",
+            "4. DEPLOYMENT TASKS, a separate step under the same approval — `create_campfire_deployment_tasks`,",
+            "   ONE call carrying every manual item, each classified with `taskKind` and `expectedMinutes`.",
+            "   Neither is written to Campfire; they ride the telemetry event as shape. You know both at the",
+            "   moment you decide you cannot automate the work; nobody recovers them afterwards.",
+            "",
+            "THE PLAN'S DEVIATION LIST IS FOR THE OPERATOR REVIEW, NOT FOR A CAMPFIRE FIELD. Every disclosed",
+            "difference is scoped to that component's final delivery, the same rule its Configuration Item",
+            "row's own description follows, so the two never disagree. Speak them; do not paste them anywhere.",
+            "",
+            "CONFIGURATION ITEMS ARE WHAT A REQUIREMENT IS BUILT FROM, not a log of this run's deltas — a",
+            "component the requirement owns that already existed still belongs on its manifest. DERIVE them,",
+            "never enumerate them from memory.",
+            "",
+            "A DELIVERED ROW WHOSE POST-DEPLOY TRUTH IS UNCONFIRMED IS HELD, PER ROW. Every confirmed row writes",
+            "normally, so one ambiguous wave never strands the manifest. Never turn an ambiguous deploy or a",
+            "roll-up counter into evidence that the record matches.",
+            "",
+            "AN OBSERVED DIFFERENCE ON AN ASYNC SETTING IS A CLAIM TO VERIFY, NOT A FACT TO RECORD. A sharing-model",
+            "change kicks off a recalculation and a read taken before it finishes reports the OLD value",
+            "(live-caught: an OWD-private wave read back `sharingModel=ReadWrite`). Re-read after it settles; if",
+            "the org now shows the approved value, do not disclose a deviation that no longer exists.",
+            "",
+            "VERIFY THE WRITEBACK AGAINST THE CONSULTANT ORG, not the deploy target:",
+            "`sf_read {sessionId, targetOrg: \"campfire\", args: [...]}` resolves it from the session. The",
+            "Configuration Item's lookup to its requirement is `Requirement__c` / `Requirement__r`. Query the",
+            "external ids YOU wrote; Campfire's own automation files Deployment Tasks of its own beside them",
+            "seconds later, and those are Campfire working, not duplicates to delete.",
+            "",
+            "THEN `close_batch {sessionId}`, AS THE LAST TOOL CALL OF THE RUN — after the final wave and any",
+            "writeback, and EQUALLY when the run ended badly. `advance_phase` never replaces it: this tool records",
+            "where the run stands, and `close_batch` is the only thing that states the batch's terminal RESULT,",
+            "assembles the closing evidence and ships everything waiting on the end of the run. A run you do not",
+            "close reads as ABANDONED on the IN2 dashboard however well it went.",
+            "",
+            `It RETURNS \`operatorPage\` — the operator's results page, ALREADY RENDERED from the persisted counts.`,
+            `PASTE IT VERBATIM as the top of your reply, then write only what belongs BELOW THE PASTED BLOCK —`,
+            `everything after the \`=== END OF BLOCK\` fence, which is the boundary. The block's own`,
+            `\`### Still to do\` heading appears inside it only when work remains; a fully automated run has none.`,
+            `Below the fence, in order: the manual items, the Campfire count (the tool cannot read Campfire),`,
+            `rollback, optional checks, notes, and the technical section. Do not recompose or re-count it —`,
+            `see ${OPERATOR_VOICE_PATH}.`
+        ].join("\n")
+    }
+};
+export function chapterBrief(chapter) {
+    return BRIEFS[chapter];
+}
+/** Every chapter has a brief — asserted here so a chapter added to `CHAPTERS` cannot ship empty. */
+export function chaptersWithoutBrief() {
+    return CHAPTERS.filter((chapter) => !BRIEFS[chapter]);
+}

package/dist/core/claudeAssets.js

@@ -0,0 +1,61 @@
+// Register the package's skills and agent definitions into ~/.claude.
+//
+// Runs at every server start, and that timing is the point. The copy used to live in the payload
+// installers and (after QA round 1 caught the gap) in the updater — under npm there is no updater
+// hook to hang it on, and npm's own lifecycle scripts are installed with --ignore-scripts on the
+// update path by design. Server start is the one moment that provably runs on every machine after
+// every update, so it is where the skills stop being stale. A machine whose server got newer while
+// the instructions describing how to drive it did not is a silent and particularly confusing kind
+// of stale (live-caught on testers' machines during QA round 1: the analyzer agent file was
+// missing, so every analyzer fanned out UNSCOPED, with every banned tool shipped into its context).
+//
+// Best-effort by contract. A skill that cannot be written must never fail a server start: the
+// server is the thing being started, and it works without them.
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { SERVER_ROOT } from "./install.js";
+export async function installClaudeAssets() {
+    await installSkills();
+    await installAgents();
+}
+async function installSkills() {
+    const source = path.join(SERVER_ROOT, "skills");
+    const dest = path.join(os.homedir(), ".claude", "skills");
+    try {
+        const entries = await fs.readdir(source, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const to = path.join(dest, entry.name);
+            // Replace rather than merge: a file left behind by an older version is a set of
+            // instructions that disagrees with the server shipping beside it.
+            await fs.rm(to, { recursive: true, force: true }).catch(() => { });
+            await fs.mkdir(dest, { recursive: true });
+            await fs.cp(path.join(source, entry.name), to, { recursive: true });
+        }
+    }
+    catch {
+        // No skills in the package, or an unwritable ~/.claude — neither is worth failing a start.
+    }
+}
+async function installAgents() {
+    const source = path.join(SERVER_ROOT, "agents");
+    const dest = path.join(os.homedir(), ".claude", "agents");
+    try {
+        const entries = await fs.readdir(source, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith(".md"))
+                continue;
+            // Per-file replace, never a directory wipe: ~/.claude/agents is the user's directory and
+            // holds agents we never shipped. A stale copy of OUR file is overwritten — an old allowlist
+            // either hides a tool this build needs or re-admits one it removed — but everything else
+            // survives.
+            await fs.mkdir(dest, { recursive: true });
+            await fs.copyFile(path.join(source, entry.name), path.join(dest, entry.name));
+        }
+    }
+    catch {
+        // No agents in the package, or an unwritable ~/.claude — neither is worth failing a start.
+    }
+}