in2-agent-server 0.20260821.185429

package/reference/templates.md

@@ -0,0 +1,233 @@
+# Scope-sheet templates — what the operator sees before they approve
+
+Designed with the operator, 2026-08-03. The approval card used to carry the assumptions and
+little else — the operator implicitly agreed to everything else without a way to *see* it. The
+scope sheet fixes that: a full enumeration of what is about to happen in the org, rendered as
+its own message immediately BEFORE the approval card, so approval is informed at batch scale
+and the operator's sense of the batch's true extent is set before anything executes.
+
+This file holds two layouts. Read both, then pick per batch — the choosing guidance is at the
+end. Both share the same header, signals, and mandatory blocks; only the body's organizing axis
+differs.
+
+**Ordering is fixed and deliberate:** scope sheet → approval card → (beta, when the feedback
+tools are present) the manual-time estimate card → first deploy. The sheet informs the consent;
+the card stays a clean consent gate; the estimate is asked after approval but before execution.
+
+**Ask the estimate card plainly, and never explain to the operator why it comes there.** Why it
+sits at that point is a measurement concern of ours, not a fact about their batch. QA round 2
+caught the tool reciting that argument back to the person it was measuring, who repeated it and
+called it weird — the same defect as round 1's meta-commentary, on a new surface.
+
+## Data sources — nothing new is collected
+
+Everything composes from what you already hold by the time you reach the approval gate:
+
+- `plan.json` per requirement: `components` (typeName, fullName, action, `operatorDecidedFacets`
+  — already human-readable), `assumptions` (what/rationale), `blockers` + the operator's answers,
+  `deletes`.
+- The question-round answers (what the operator actually chose — every deviation cites one).
+- `plan_waves` output: step count and which wave each component rides.
+
+No new tools, no org reads. If you cannot fill a section from these, the gap is in your
+analysis, not in this template.
+
+## Inline signal vocabulary — fixed, never extended ad hoc
+
+| Signal | Meaning |
+|---|---|
+| ⚠️ | removal, or partial delivery |
+| 🔀 | differs from the requirement as written |
+| 🤝 | covered by another requirement's work — nothing extra built |
+| 📋 | becomes a manual task for the operator |
+| 🤔 | judgment call in force |
+
+The signals sit inline beside the exact outcome they qualify — never in a standalone column.
+A row with no exception gets no signal. The signal is only a scan aid: the outcome itself must
+still say plainly what differs, is partial, is covered, or becomes manual.
+
+## The header scoreboard — always first, one line
+
+> **N requirements → M components · X objects · K verified steps · deletions and manual-task
+> counts · anything held back**
+
+Counts are the batch's extent at a glance. Anything surprising in the counts (a removal, a
+held-back item, a covered requirement) must also appear in a body section — the header surfaces
+the exception, the body explains it.
+
+## The mandatory blocks — every layout carries these, after the body
+
+Composition rules that apply to every block: **every line opens with the artifact it lands on, in
+bold**; write prose with a spine, not bullet fragments; operator language per
+`operator-voice.md` (no verdict names, no file paths).
+
+### ⚠️ Removals
+
+Every deletion gets its own block — **never a table row among creates**. Each states: the
+rehearse-first step ("I'll validate the removal with the org first without changing anything,
+then remove it for real"), and the honest limit, explicitly ("I can prove nothing *in this
+batch* uses this view; a report or bookmark elsewhere in the org I cannot rule out from here").
+Asked-for removals that are NOT happening belong here too, with the reason and whose call it
+was — a removal the operator expects and doesn't see is as alarming as the reverse.
+
+### 🔀 Where this differs from the requirements as written
+
+Every deviation cites the operator answer that caused it ("per your Q3 answer"). Three shapes
+belong here: requirements that GREW beyond their text, contradictions resolved *against* one
+requirement's text, and acceptance criteria that will not be met. This is the block that keeps
+a clarification round from silently rewriting the contract — the operator re-sees what their
+answers did before approving the result.
+
+### 📋 Handed to you as manual tasks
+
+Each with the reason it is manual ("both live on your admin Profile, and deploying that Profile
+from here risks overwriting settings this batch has nothing to do with").
+
+### 🤔 Judgment calls you're approving
+
+The assumptions, artifact-first, in operator language. Not a restatement of every `plan.json`
+assumption — the ones an operator would want to have known they agreed to.
+
+### Safeguards footer
+
+One line: validate-before-apply, read-back-after, a refused step applies nothing. Rehearsal
+note when a removal exists.
+
+---
+
+## Layout 1 — Grouped table (RECOMMENDED DEFAULT)
+
+The table's rows are requirements; the table's GROUPS are org targets. Each object/area gets a
+header line carrying its one-sentence org-delta summary, then `Req | What lands here` rows
+beneath. A requirement whose pieces land in two groups appears in each with the relevant
+slice and a pointer ("its queue & group land below ↓") — nothing double-counted, nothing
+hidden. A single-object batch collapses gracefully to one group.
+
+Choose when: most batches. It keeps per-requirement accountability ("did you hear all of me" is
+answerable by inspection), gains org locality (everything touching one object is contiguous),
+and inline signals make exceptions pop without adding a low-information column.
+
+### Worked example — the CF80 batch (15 reqs, 25 components, real session)
+
+> ## 📋 Scope of this delivery — before you approve
+> **15 requirements → 25 new components · 2 new objects · 4 verified steps · nothing deleted ·
+> 2 manual tasks · 1 requirement covered by another's work**
+>
+> ### 📦 CF80 Intake Request — *new object · 8 fields · 4 automations · full page/access set ·
+> ships **Private**, not Public-as-written 🔀*
+>
+> | Req | What lands here |
+> |---|---|
+> | 3A | 🔀 the object itself — **Private sharing per your answer**, not Public Read/Write as written |
+> | 3B | 6 core fields: email · status *(6 values, default New)* · category · due date · value · notes |
+> | 3C | reason picklist, values filtered by category |
+> | 3D | days-remaining SLA formula + help text on the core fields |
+> | 3E | page layout + compact layout |
+> | 3F | validation: due date required once Assigned |
+> | 3G | *Open Intake Requests* list view |
+> | 3H | tab |
+> | 3I | *Intake Request User* permission set |
+> | 3J | follow-up task flow |
+> | 4A | escalation flow: overdue high-value → Triage queue |
+> | 4C | 🔀 owner-based sharing rule + High-Value approval *(its queue & group land below ↓)* |
+>
+> ### 📦 IN80 Test Console — *new object, labels corrected "in78"→"in80" 🔀*
+>
+> | Req | What lands here |
+> |---|---|
+> | T1 | 🔀 the object + Priority picklist with **labels corrected to “in80”** (High/Medium/Low) |
+> | T2 | 🤝 **Covered** — the unnamed picklist is T1's Priority field; nothing extra built |
+>
+> ### 🌐 Org-wide — *1 new app · 1 queue · 1 group · 2 manual tasks for you 📋*
+>
+> | Req | What lands here |
+> |---|---|
+> | 4B | 🔀 *Operations Console* app + utility bar with History + Notes; **CTI dropped because none is configured** · 📋 app visibility and tab default become manual tasks |
+> | 4C | *Intake Triage* queue + *Intake Managers* group |
+>
+> ### 🔀 Where this differs from the requirements as written
+> - **CF80 Intake Request ships Private, not Public Read/Write.** Two of your requirements
+>   collided: 3A pins the object Public Read/Write, 4C needs an owner-based sharing rule
+>   Salesforce refuses on a Public Read/Write object. You picked the rule, so 3A's sharing line
+>   is deliberately not honored as written — that one answer reshaped both requirements.
+> - **IN80 Test Console's labels ship corrected** ("in80", not the "in78" in the text) — a
+>   leftover from the source this was copied from, fixed on your instruction.
+> - **The utility bar drops "Open CTI softphone"** — no CTI is configured in this org; History +
+>   Notes ship.
+>
+> ### 📋 Handed to you as manual tasks
+> - **App visibility and tab default for System Administrator** — both live on your admin
+>   Profile, and deploying that Profile from here risks overwriting settings this batch has
+>   nothing to do with. Two Campfire tasks instead, per your answer.
+>
+> ### 🤔 Judgment calls you're approving
+> - **Request Status** and the other picklists: labels, restricted value sets, and ordering
+>   mirror your delivered CF79 twin where the text is silent; default status is **New**.
+> - **Formula and help text wording** follows this object family's house style.
+>
+> **Safeguards:** 4 dependency-ordered steps, each validated before applying, every setting
+> read back after; a refused step applies nothing.
+
+## Layout 2 — Flat table + thematic blocks
+
+One requirement per row (`Req | You asked for | What will happen`), then the mandatory
+blocks. No grouping.
+
+Choose when: requirements are many but org targets are few, and the RISKS dominate the story —
+the gathered blocks let the operator audit just the dangerous parts in three glances, and a
+one-object batch gains nothing from group headers.
+
+### Worked example — the RV batch (4 reqs, deletion-heavy, partial delivery, real session)
+
+> ## 📋 Scope of this delivery — before you approve
+> **4 requirements → 5 additions to PV Asset · 1 removal (rehearsed first) · 2 asked-for
+> removals not happening, on your instruction · 3 build steps + 1 removal step**
+>
+> | Req | You asked for | What will happen |
+> |---|---|---|
+> | RV-01 | Audit date stamp + no-future rule | ➕ date field + validation rule + **page placement you added** 🔀 |
+> | RV-02 | Freshness flag, stale after 365 days | ➕ formula checkbox; **blank counts as stale** 🔀 |
+> | RV-03 | Delete field, rule, list view | ⚠️ **only the list view goes; field + rule stay** |
+> | RV-04 | Surface the flag read-only | ➕ layout + permission set updated |
+>
+> ### ⚠️ Removals
+> **The *Active High Value* list view is the only thing being removed.** I'll rehearse the
+> removal with the org first — a validation pass that changes nothing — then remove it for
+> real. One honest limit: I can prove nothing *in this batch* uses this view; a report or
+> bookmark elsewhere in the org I cannot rule out from here.
+>
+> **The audit date field and its rule were asked for gone, and they're staying.** RV-03 wants
+> all three retired, but RV-02's freshness flag is *calculated from* the audit date — deleting
+> it would break the thing this same batch builds. You chose to keep them, so RV-03 delivers
+> partially and gets recorded that way, reason on the record.
+>
+> ### 🔀 Where this differs from the requirements as written
+> - **PV Last Audit (the new field)** ends up on the page with edit access — as written, RV-01
+>   left it invisible to every user. That's your Q3 answer, and it's the one place this batch
+>   *grew* beyond its text.
+> - **PV Audit Stale (the formula)** treats a never-audited asset as stale — the requirement
+>   only defined assets that *have* been audited. Your Q2 answer filled the gap.
+> - **RV-03's acceptance criteria will not be met** — it says none of the three should exist
+>   afterwards; one removal ships.
+>
+> ### 🤔 Judgment calls you're approving
+> - **PV Last Audit**: dated *today* saves — only strictly-future dates refuse. No field
+>   history, though this object tracks history elsewhere; the requirement didn't ask.
+> - **PV Audit Stale**: literal 365 days, strict boundary — exactly 365 days ago reads *not*
+>   stale. Placed in *Asset Details*, right after *PV Risk Weighted Value*.
+> - **PV Audit Date Not Future**: active the moment it lands.
+>
+> **Safeguards:** every step is validated by Salesforce before it applies, every setting read
+> back after it lands, and a refused step changes nothing.
+
+## Choosing, in one breath
+
+Default to **Layout 1**. Fall back to **Layout 2** when one or two org targets make grouping
+pointless and the risk blocks are the story. Whichever you pick: the mandatory blocks are not
+optional, the signals are the fixed five and sit beside the outcome they qualify, the header
+scoreboard leads, and every deviation names the answer that caused it.
+
+*An org-centric tree — artifacts first, deviations annotated at the point of impact — was the
+third layout here and was dropped 2026-08-04: it renders the same content as Layout 2 while
+scattering the deviations through the tree, so an approver auditing only the risky parts has to
+read everything. Layout 2's gathered blocks are that layout done better.*