in2-agent-server 0.20260821.185429

package/reference/deployability-cribs.md

@@ -0,0 +1,119 @@
+# Deployability cribs — what is provably deployable, what is DML, what is genuinely impossible
+
+Every verdict here was proven live in the client QA org (00Dfn00000BFjbBEAT, API v67.0,
+2026-08-14) — deployed, read back, and torn down. Nothing below is inferred from docs alone.
+Consult this BEFORE routing a component to a manual `coverageRoute`: QA round 2 lost 12 of 17
+manual handoffs to claims this file now refutes, and three of them shipped to the operator as
+"no deployment can create it" — stated as platform fact, and wrong.
+
+The rule this file exists to enforce: **you may only claim a platform limit that this file
+already lists as impossible.** Anything else you believe undeployable is a `coverageRoute` with
+your evidence attached (the org's own refusal, not your reasoning), never a "cannot".
+
+## Deployable NOW through the direct tier — with the shape that actually works
+
+**Quick action on a page layout** — `Layout` → `platformActionList`, NOT `quickActionList`.
+The list is a WHOLE-SECTION REPLACEMENT: include every standard action you want to keep
+(`Edit`, `Delete`… as `actionType` **StandardButton**, your action as **QuickAction**), with
+unique, ascending, contiguous `sortOrder` from 0. The two live-verified rejection texts:
+duplicate sortOrder → `duplicate value found: PlatformActionListId duplicates value…`; a
+standard button typed as QuickAction → `no QuickAction named Edit found`. Both were injected
+deliberately and reproduced character-for-character — the QA "REJECTED_BY_ORG" on this type was
+our XML, not the platform. Also: omission does NOT revert — removing an action later means
+re-deploying the full list minus that action, not deleting the element.
+
+**Utility bar sizing** — a `FlexiPage` with `<type>UtilityBar</type>` named by the app's
+`utilityBar` string. There is no `UtilityBar` metadata type. Sizing rides
+`componentInstanceProperties` with `<type>decorator</type>`, nested
+`flexiPageRegions > itemInstances > componentInstance` (the flat `componentInstances` shape is
+rejected outright in v67.0), and the FlexiPage needs its `<template>`. Decorator support is
+PER-COMPONENT and server-enforced: `notes:utilityBarNoteList`, `macros:macroUtilityItem` refuse
+sizing, and so do components no list predicts (`runtime_sales_todo_list:…` refused live). Treat
+"does this component take width/height" as probe-to-discover via a checkOnly validate, never as
+known.
+
+**Lightning record page activation** — believed permanently manual for a full QA round; it is
+not. Org default: `CustomObject` → `actionOverrides` (`actionName` View, `formFactor` Large,
+`type` flexipage). App/profile scope: `CustomApplication` → `profileActionOverrides` — and
+`<profile>` is REQUIRED there (live: `Required field is missing: profile`). There is no
+app-wide-default single element: activating "for app X" means enumerating profiles, which is a
+scoping question for the card, not a deploy detail. `pageOrSobjectType` takes the sObject API
+name for record pages — Salesforce's own field-table doc claiming otherwise is contradicted by
+its own sample. Neither override is removable via destructiveChanges: retrieve, set `<type>`
+back to `Default`, redeploy.
+
+**Compact layout assignment** — `CustomObject`/`RecordType` → `compactLayoutAssignment`.
+
+**Record type visibility** — permission set metadata `recordTypeVisibilities`. Two hard
+asymmetries, both live-confirmed: a permission set cannot assign Master, and cannot set a
+DEFAULT record type — default is Profile-only, so a requirement that includes "default RT"
+forces the Profile route for that one facet.
+
+**Tab visibility** — permission set `tabSettings`. Values are `Available`/`Visible` — there is
+no `Hidden` (absence is hidden). Read-back trap: metadata `Visible` reads back through the
+sObject surface as `DefaultOn`; a verifier string-comparing the two shapes will report a false
+mismatch.
+
+**Queue membership (metadata route)** — `Queue` → `queueMembers` deploys clean. Membership has
+a second, DML route below; prefer this one when the queue itself is already in the wave.
+
+**Lightning email template** — deployable, with one prerequisite that is NOT metadata-only:
+the enhanced folder. `EmailTemplateFolder` as a metadata type is DEAD in practice — the CLI
+registry aliases it to `emailfolder`, never registers its suffix, and the org rejects both type
+names in package.xml; one CLI path even prints `EmailFolder … Created` while creating NOTHING
+(a false success — trust only read-back). The working shape: create the folder as a `Folder`
+sObject row (`Type='EmailTemplate'` — plain DML), then deploy the `uiType=SFX` template into
+it. `EmailTemplateSettings.enableTemplateEnhancedFolderPref` must be true first (check it — it
+was already true in the QA org). Keep folders flat: nested Lightning template folders are
+broken server-side (Salesforce Known Issue a028c00000zIpaDAAS). If a suitable enhanced folder
+already exists, the template alone IS a pure metadata deploy.
+
+**Role** — deploys, but the XML rejects access levels below the object's OWD; author the role
+against the org's sharing model as projected, not the requirement's wish.
+
+## Records, not metadata — REAL, but a different write path (DML), not "impossible"
+
+Every one of these is a plain sObject row, insertable in seconds via REST. The Metadata API not
+carrying them does NOT make them manual — it makes them data writes. Until the toolset exposes
+a DML write lane, these route to a Deployment Task — but the task text says "awaiting the DML
+write path", cites this file, and NEVER claims the platform cannot do it. INTERIM: the
+supervisor may OFFER to execute these directly, under the strict card-and-consent protocol in
+`scoped-dml-interim.md` — that file, not this list, is the permission. The moment the lane
+exists, this whole cluster stops being manual:
+
+- Public group / queue membership — `GroupMember` (idempotent: duplicate insert returns the
+  existing row). A ROLE joins a group via its shadow group (`SELECT Id FROM Group WHERE
+  Type='Role' AND RelatedId='<roleId>'`; `RoleAndSubordinates` variants express the
+  "(include subordinates)" distinction — it is expressible, not a judgment call).
+- Permission set assignment — `PermissionSetAssignment` (NOT idempotent: `DUPLICATE_VALUE` on
+  re-insert; pre-check by SOQL). PSG variant via `PermissionSetGroupId` — poll
+  `PermissionSetGroup.Status` until `Updated` first, and note a recalculating PSG WRITE-LOCKS
+  its member permission sets (`…is updating. You can make edits…when the group update
+  completes`), so the poll belongs before EVERY permission-set write whose parent is in a PSG.
+- Field/object permissions as data — `FieldPermissions` / `ObjectPermissions` rows
+  (PermissionSet parents only; send the whole dependency chain in one payload: Edit needs Read).
+- App visibility / custom permission grants — `SetupEntityAccess` (TabSet / CustomPermission).
+- Role assignment to a user — `User.UserRoleId` PATCH.
+- Custom setting VALUES — list rows are plain inserts; the ORG-DEFAULT row of a hierarchy
+  setting needs `SetupOwnerId` = the org's `00D` id EXPLICITLY. The wrong-way insert (user id)
+  SUCCEEDS SILENTLY and creates a user-scoped row — only `SetupOwner.Type` distinguishes them
+  on read-back.
+
+## Genuinely impossible — the complete list; claim nothing beyond it
+
+- **Grant Access Using Hierarchies** (the checkbox; custom objects only) — no API of any kind.
+  The one platform blocker inside the certified types. OWD itself (`sharingModel`) IS
+  deployable.
+- **Queue on a master-detail child** — detail side has no Owner field. A requirement asking for
+  it is a requirement defect; say so on the card.
+- **Notes / Macros utility panel sizing** — the components reject decorators headlessly AND in
+  App Builder.
+
+## Two verifier rules this file adds
+
+- **Read-back beats deploy status.** Two live false-successes: the `EmailFolder Created`
+  no-op above, and a rolled-back destructive deploy that still printed a "Deleted Source"
+  table (only the JSON `numberComponentErrors` was honest). A green deploy is a claim; the
+  read-back is the fact.
+- **Layout API names contain spaces** (`Obj__c-My Layout Name`) — anything treating component
+  identifiers as space-free corrupts on them.

package/reference/operator-voice.md

@@ -0,0 +1,141 @@
+# Operator voice — how the supervisor talks to the human
+
+*The pre-approval scope sheet has its own guide — `templates.md`, beside this file: three
+layouts, worked examples, and the fixed flag vocabulary. This file governs the words; that one
+governs the shape.*
+
+The operators are Salesforce consultants: fluent in record types, permission sets, validation
+rules, App Manager — and complete strangers to this harness. Reviewing real run transcripts
+(CF80, SM301, the Pinsley judgment tests) showed one consistent defect: the DECISIONS were
+excellent and the VOCABULARY undercut them. "All 25 components are delivered and DIFF_VERIFIED"
+is a triumphant sentence that reads, to its actual audience, like a warning.
+
+## The rule: two surfaces
+
+**Operator surfaces** — question cards, progress lines between tool calls, and the end-results
+page. These speak *Salesforce and business outcomes*. Never: internal verdict names, pipeline
+vocabulary, lint rule names, file paths, facet counts.
+
+**Engineering surfaces** — evidence bundles, plan.json, verdict.json, telemetry. These keep full
+internal precision. Nothing in this guide waters them down.
+
+The line is the audience, not the topic: "the sharing rule needs the object to be Private" is
+operator language (a Salesforce fact); "the sharing rule linted clean against the wave-3
+post-image" is not (a harness fact).
+
+## Translation table
+
+| Internal (keep in evidence) | What the operator reads |
+|---|---|
+| `DIFF_VERIFIED` | Deployed and verified — every setting matches the specification ✅ |
+| `DELIVERED_WITH_DRIFT`, drift classified benign | Deployed and verified — Salesforce recorded a few cosmetic differences; each one checked, all harmless ✅ |
+| `DELIVERED_WITH_DRIFT`, unclassified | Deployed; double-checking a few readings before I call it done |
+| `REJECTED_BY_ORG` | Salesforce declined this step, so nothing from it was applied — here's why and what I recommend |
+| `VALIDATED` (dryRunOnly) | Salesforce accepted everything in a practice run — nothing has been changed yet |
+| `LINT_BLOCKED` | My pre-flight checks stopped this before it touched your org — fixing and retrying |
+| `AMBIGUOUS_DELIVERY` | The change was sent but the confirmation timed out — checking the org before doing anything else |
+| wave N | step N of M |
+| lint / lint ladder | pre-flight checks |
+| checkOnly | Salesforce's own validation run (changes nothing) |
+| projection / post-image | a fresh read of what's actually in your org |
+| evidence bundle / bundle path | "the full technical log is saved with this session" — never show the path |
+| intent check / N facets matched | every setting was compared against the spec — (drop the numbers) |
+| OWD / sharingModel | who can see these records by default |
+| full-file-replace hazard | this kind of change replaces the whole page/profile, so I carry everything existing forward before touching it |
+| coverage route / deployment task raised | this piece can't be deployed as metadata — I've logged it as a tracked to-do with exact steps |
+| `direct_apply` returns `operatorSummary` | **relay that string** — it is the sanctioned translation of the verdict |
+
+## Cards
+
+Everything already right about the cards stays: exactly one recommended option, honest
+trade-offs, business consequences, the operator's own past answers cited, and "nothing has
+changed in your org yet" wherever true. What changes:
+
+- **Lead with the business question in one sentence.** "Two requirements disagree about who can
+  see these records — which wins?" Mechanism, if needed at all, goes inside option descriptions,
+  one clause max.
+- **Options are verdicts about outcomes**, not procedures: "Keep records private and the sharing
+  rule works" beats "OWD Private, sharingOwnerRules deploy".
+- An approval card promises outcomes and safeguards, not pipeline stages: "I'll build this in
+  5 steps. Salesforce validates each step before it's applied, I verify every setting after it
+  lands, and I stop and show you anything unexpected."
+
+## Progress lines (the operator is watching)
+
+- The activation confirmation carries the `Live progress:` URL from the `activate_session` result
+  verbatim, framed as watch live progress here — it is the one place the operator sees the run
+  move, and a link retyped from memory points at somebody else's session.
+- Good: "Step 2 of 5 — the fields, the tab and both queues. ✅ Deployed and verified."
+- Good, on a snag: "Salesforce flagged one item in this step — adjusting and retrying. Nothing
+  incorrect has been applied."
+- Bad (real transcript, from the run that made this a rule): "wave assembly copied the
+  .email-meta.xml files but dropped their sibling .email content bodies." — that sentence belongs
+  in the session log and the final technical footnote, not the live narration.
+
+## The end-results page — it arrives rendered
+
+`close_batch` returns `operatorPage`: the top of this page, already composed, from the same
+persisted numbers `scope` reports. **Paste it verbatim.** Do not reorder it, do not recompose it in
+your own words, and above all do not re-count anything in it — counting configurations by hand from
+evidence bundles at the end of a long run is how one batch reported 205 components as 94
+configurations and 147 built as 77.
+
+The rendered block covers the headline, the automation rate and its bar, the summary panel, and
+every landed configuration enumerated under the requirement that owns it. Where work is still
+outstanding it also carries a `### Still to do` heading whose COUNT it owns — and on a fully
+automated run nothing is left, so that heading is simply absent. The block's boundary is therefore
+the `=== END OF BLOCK` fence `close_batch` prints beneath it, never a heading inside it.
+
+**You write everything below the pasted block**, in this order:
+
+1. **The manual items themselves** — one line each, with the exact Setup path, a time estimate, and
+   the confirmed Campfire task id where one exists. The `DT-#####` number is the task's Campfire
+   `Name`, which `create_campfire_deployment_tasks` does not return — read it back from the
+   consultant org (`sf_read`, `Name` in the SELECT, `WHERE External_ID__c IN (…)`). Never print a
+   raw 18-character record Id, and never invent a number.
+2. **The Campfire line.** `close_batch` cannot read Campfire, so the rendered block says nothing
+   about it and this is yours: state how many Configuration Items were re-read successfully by their
+   external ids. A row held for delivery truth is excluded and named with its remedy — some rows
+   confirmed and some held is the normal shape, not a failure. If NO writeback happened or NO
+   read-back succeeded, write **“Not recorded in Campfire — <reason>”**; never let a zero imply a
+   verified writeback.
+3. **Rollback**, as prose, never a status column and never a question the operator must answer at
+   every close: **“I can prepare a rollback for your approval.”** Newly created components are
+   removed to undo them; existing configuration is restorable only where a prior version was
+   captured. If any existing-state change lacks that prior version, name the limitation here.
+4. **Optional checks** — things to tick off, specific to this batch's components. Runtime
+   verification and follow-up never inflate the manual count.
+5. **Notes worth knowing** — two or three plain sentences: decisions the operator made and their
+   consequences, anything Salesforce normalized cosmetically, anything deferred and why.
+6. **Details for your technical team** — verdicts per step, drift classifications with evidence
+   citations, session id, evidence locations. Everything above this line is readable without it.
+
+If `operatorPage` comes back empty — a batch that recorded no requirement index, or a renderer that
+failed — say what the close report shows in plain language and state that the summary could not be
+composed. Do not reconstruct the block by hand.
+
+### What the rendered block will not do for you
+
+It states no Campfire count, no time estimate, and no rollback promise, because it is rendered by a
+tool that cannot verify any of the three. Those are exactly the claims that must come from what you
+actually observed.
+
+## Voicing deviations
+
+The run does not write to the requirement record, so a deviation is never composed as a note.
+`campfire_config_item_plan`'s `requirementDisclosures` is the short, evidence-derived explanation
+of where an observed org result differs from what was approved — and it is already carried onto
+its own Configuration Item row by the writeback. This entry's job is spoken, not written: work
+every non-empty disclosure into the review, in the operator's own language — under "Notes worth
+knowing" on the end-results page, or the equivalent point in the delivery review that precedes it.
+**Do not paraphrase it back into the approved wish** — that is the one place where operator
+language could turn an observation into a claim, and it must not.
+
+The writeback mechanics themselves — held rows, async settings, external-id read-back — are the
+playbook's step 8; nothing here changes them.
+
+## What NOT to change
+
+Honesty is the product. Never soften a real failure, never skip an assumption on the approval
+card, never replace a consequence with a vibe. The goal is the same rigor arriving in the
+reader's language — a consultant who understands exactly what happened, without a glossary.

package/reference/org-read-cribs.md

@@ -0,0 +1,34 @@
+# Org-read cribs — what the org's own query surfaces do and do not prove
+
+Read this when you are doing BINDING work against a live org: establishing whether a component
+exists, resolving its API name, or confirming what an earlier read reported. These are org-shape
+facts, not tool instructions — nobody deciding whether to call `sf_read` needs them, and an
+analyzer resolving a name does.
+
+Each one is live-caught (CF79) and each cost a run.
+
+## Never conclude ABSENCE from a context-scoped UI-API view
+
+`AppDefinition` and `TabDefinition` are context-scoped UI-API views: they return EMPTY for rows
+that demonstrably exist, because what they return depends on the querying user's context rather
+than on what the org holds. A zero-row result from either proves nothing at all. If you need to
+know whether an app or a tab exists, ask a surface that answers the question.
+
+## The surfaces that DO answer it
+
+- **`CustomApplication` is tooling-queryable** — `--use-tooling-api`, `DeveloperName`. That is the
+  reliable existence check for an app.
+- **Tooling `CustomTab` returns NULL `DeveloperName` for object tabs.** That is not absence: an
+  object tab's metadata `fullName` is simply the object's API name, so there is no separate
+  developer name to return. Web and Visualforce tabs come back named correctly, so a
+  `WHERE DeveloperName != null` filter is a filter on TAB KIND, never on existence.
+- **`FlowDefinitionView`, `ProcessDefinition` and `Group` are regular-API and reliable.** Note
+  "regular-API": routing them through the Tooling API fails on every org, and a probe failure is
+  indistinguishable from "the feature is off" — which is exactly how a sweep can silently collect
+  nothing and look like a clean answer.
+
+## The general rule underneath all four
+
+A read surface that can return empty for two different reasons — "it is not there" and "you cannot
+see it from here" — cannot be used to prove the first. Pick the surface whose empty result has one
+meaning, or state in your plan that you could not establish absence.

package/reference/scoped-dml-interim.md

@@ -0,0 +1,68 @@
+# Scoped DML interim protocol — offering to run the record-writes instead of handing them back
+
+INTERIM, until the pipeline grows a DML write lane. This file authorizes ONE narrow exception to
+"never call raw `sf` mutations": the supervisor may execute the record-write mechanisms named in
+`deployability-cribs.md` ("records, not metadata" section) directly through the CLI — ONLY after
+the operator approves the exact rows on a card, ONLY against the session's bound target org, and
+ONLY for the mechanisms this file carries commands for. Anything not listed here stays a manual
+task. This protocol never expands by analogy; it expands by a new entry in this file.
+
+## When to offer
+
+At the point you would otherwise hand the operator a manual task whose mechanism appears in the
+cribs' DML cluster (memberships, assignments, FLS/object-permission rows, SetupEntityAccess
+grants, `User.UserRoleId`, custom setting VALUES, the email-template `Folder` row). Instead of
+"you need to do this in Setup", the card says: "I can run these N record-writes for you now —
+here is each one — or leave them as manual tasks." The operator picks per card, not per row.
+
+## The card — consent is to the EXACT rows
+
+The card lists every row to be written: object, field values, and the org it lands in, named the
+way the operator knows it (the target org they authenticated at activation — NEVER the Campfire
+org, whose writes flow only through the writeback tools). Approval covers exactly the rows on
+the card. A row discovered after approval is a NEW card, not an extension. Decline = the manual
+task ships as it would have anyway, with no second ask.
+
+## Execution rules
+
+- Resolve the CLI: `command -v sf` first, else `$IN2_HOME/tools/node_modules/.bin/sf`
+  (`IN2_HOME` defaults to `~/.in2-agent`). Always pass `--target-org <the session's target org
+  alias>` explicitly on every command — never rely on a default org.
+- INSERTS ONLY, plus the single sanctioned PATCH (`User.UserRoleId`, current value captured on
+  the card first so it can be restored). Never update or delete a pre-existing row under this
+  protocol — a wrong edit to someone else's row is exactly the damage the write gate exists to
+  prevent, and no card can make it reversible.
+- The probe-measured guards are MANDATORY, not advisory:
+  - `PermissionSetAssignment`: SOQL pre-check for an existing assignment first — a duplicate
+    insert throws `DUPLICATE_VALUE`; an existing row means DONE, not an error.
+  - PSG assignment (`PermissionSetGroupId`): poll `PermissionSetGroup.Status` until `Updated`
+    first — and before ANY permission-set write whose parent set belongs to a PSG (a
+    recalculating group write-locks its members).
+  - Hierarchy custom setting org default: `SetupOwnerId` = the org's `00D` id explicitly. The
+    wrong-way insert (user id) SUCCEEDS SILENTLY as a user-scoped row — read back
+    `SetupOwner.Type` and refuse to report success unless it is the org.
+  - `ObjectPermissions`: the whole dependency chain in one payload (Edit needs Read; ModifyAll
+    needs Read+Edit+Delete+ViewAll).
+  - A ROLE joining a group: resolve the shadow group (`SELECT Id FROM Group WHERE Type='Role'
+    AND RelatedId='<roleId>'`; `RoleAndSubordinates` for "(include subordinates)").
+- Read-back is the ONLY success. Query every written row back by Id and show the Ids on the
+  result line. CLI exit 0 is a claim (two live false-success modes are on record).
+
+## Recordkeeping — nothing about the ledger changes
+
+- The Deployment Task for the item is still filed, then marked `Complete` with the written row
+  Ids in its description: "automated via scoped CLI with operator approval on <date>; rows:
+  <Ids>; undo: delete these Ids." The row Ids ARE the rollback plan — record them in the
+  session's notes too, because a batch rollback must delete them (GroupMember, QueueSobject and
+  SetupEntityAccess have no update verb; undo is delete).
+- Configuration Item writeback for these rows follows whatever the mapping table supports today;
+  where the edge type has no CI convention yet, the completed Deployment Task is the record.
+
+## Say this plainly to the operator (the honest limit)
+
+This removes the LABOR, not yet the metric. The automation rate is computed from what the
+approved plans own; an item routed to manual and then executed under this protocol still counts
+on the manual side of that rate until the real DML lane makes these rows first-class planned
+components. Do not imply the certified number improves because the operator stopped clicking —
+the number the contract reads moves when the lane lands, and pretending otherwise is the exact
+counting sin QA round 2 documented.