in2-agent-server 0.20260821.185429

package/README.md

@@ -0,0 +1,369 @@
+# cc-mcp-server
+
+MCP (Model Context Protocol) stdio server that turns Campfire Salesforce requirements into verified
+org changes, driven by a Claude Code supervisor.
+
+**Standalone.** No `workspace:*` dependencies — it resolves nothing outside published npm packages,
+so it publishes to the public npm registry as **`in2-agent-server`** (bins: `in2-agent-server`,
+`in2`), stamped and shipped by `scripts/release.mjs`.
+
+- **What the tools are and how they compose:** [`docs/TOOL-SURFACE-AUDIT.md`](docs/TOOL-SURFACE-AUDIT.md)
+  — full inventory, the happy-path flow, the failure loops.
+- **How the supervisor runs a batch:** [`harness/supervisor-playbook.md`](harness/supervisor-playbook.md) — the deep reference.
+- **What actually reaches a production session:** [`src/core/supervisorContract.ts`](src/core/supervisorContract.ts)
+  — shipped as the server's MCP `instructions`, so it arrives regardless of the session's cwd.
+
+## The loop
+
+```
+activate_session          redeem a Campfire code: auth the org, bind it, grant write, import reqs
+  → project_org           read the org slice — ground truth; asserted API names are untrusted
+  → (analyzers)           one per requirement, writing requirements/<extId>/plan.json
+  → direct_lint           schema + lemma + referential tiers, locally, in milliseconds
+  → direct_apply          checkOnly → deploy → re-project → three-way diff → verdict + evidence
+  → campfire_config_item_plan / campfire_write_config_items
+  → close_batch             state the terminal result, write the evidence, ship everything
+```
+
+Carry the **`sessionId`** and nothing else: the session owns the target org, the Campfire org, the
+authored trees and the evidence bundles. Author each wave to `<session>/authored/<wave>/`, then both
+`direct_lint {sessionId, wave}` and `direct_apply {sessionId, wave}` derive that path themselves.
+
+### Chapters
+
+The loop has nine named chapters — `activation`, `intake`, `partitioning`, `parallel-analysis`,
+`clarification`, `scope-approval`, `delivery`, `review-results`, `writeback-close` — and
+`advance_phase {sessionId, completed, entering}` marks each boundary. Three things ride on one call,
+and they are bound together because any two without the third is worse than the whole:
+
+- **The position is recorded**, appended to `<session>/phases.jsonl`. Everything else in a session
+  directory says what a run *produced*; nothing else says where it *got to*, and a chapter entered
+  but never finished leaves no other trace.
+- **The evidence so far is shipped** — outbox, parcels, transcript. `close_batch` is the only other
+  flush and it runs at the end, so before this a run that died mid-flight shipped *nothing*: its
+  events sat in the local outbox with no scheduled drain, and its transcript, which has no outbox at
+  all, was simply lost.
+- **The entering chapter's expanded instructions come back.** The resident contract is a skeleton on
+  measured evidence that clients truncate it at ~2 KB, so per-step doctrine increasingly arrives
+  here — at the moment it applies, rather than an hour early in the playbook.
+
+Small batches legitimately skip `partitioning`, `parallel-analysis` and `clarification`; the rest are
+load-bearing and skipping one is refused by name. Ending a run early is legal from anywhere.
+**`advance_phase` never replaces `close_batch`** — entering the last chapter is not closing the batch.
+
+`resume_session {sessionId}` picks up a run a previous session left unfinished: it reconstructs the
+position from the ledger plus the artifacts, reports where the two disagree rather than reconciling
+them, and **checks the org auth instead of assuming it** — an activation-minted token lasts about a
+day, so the commonest resume has intact artifacts and a dead org, which is a card for the operator
+and never a re-authentication.
+
+## Tools
+
+| Group | Tools |
+|-------|-------|
+| Session + auth | `activate_session`, `create_session`, `import_requirements`, `org_login` |
+| Grounding | `project_org`, `sf_read`, `list_components`, `describe_object` |
+| Delivery | `plan_waves`, `direct_lint`, `direct_apply` |
+| History | `direct_history` |
+| Rollback | `direct_rollback` |
+| Operator | `ask_operator`, `resolve_blocker` |
+| Run structure | `advance_phase`, `resume_session`, `close_batch` |
+| Self-update | `update_server` (read-only unless `apply: true` — `npm install -g`s the published version, which the NEXT conversation runs; the current session keeps its loaded build) |
+| Campfire writeback | `read_campfire_requirements`, `update_campfire_requirements`, `campfire_config_item_plan`, `campfire_write_config_items`, `create_campfire_deployment_tasks`, `create_campfire_requirements`, `mirror_requirements` |
+
+`direct_apply` verdicts: `LINT_BLOCKED` | `REJECTED_BY_ORG` | `VALIDATED` (dry run) | `DIFF_VERIFIED`
+| `DELIVERED_WITH_DRIFT` | `AMBIGUOUS_DELIVERY`. `DIFF_VERIFIED` is mechanical read-back proof of
+metadata **shape** — never runtime behavior.
+
+## Org history
+
+Each state-changing verdict (`DIFF_VERIFIED`, `DELIVERED_WITH_DRIFT`, `AMBIGUOUS_DELIVERY`) overlays
+its post-image and its deployed source XML onto a per-org mirror at
+`.local/cc-mcp/orgrepo/<orgId>/` and commits — **only if the tree changed**, so a re-delivery of
+unchanged content records nothing. The other three verdicts never reach it. `direct_history` reads
+it back; no operator-facing git concept exists above that tool.
+
+The commit is a **post-verdict side effect**: a mirror that cannot write lands a note and never
+fails, delays, or masks a delivery. Materialization is deterministic — fixed identity, timestamps
+from the bundle's mutation window, a total sort key of (window start, session id, wave) — so any
+machine holding the same evidence bundles rebuilds byte-identical history. That also means **SHAs
+are display aliases**: a rebuild rewrites every one, so nothing may persist them (address a wave by
+`(sessionId, wave)`).
+
+Two honest limits, both surfaced rather than papered over. The mirror covers **what this install
+delivered** — a client admin's edit in Setup and another consultant's wave from another machine are
+both invisible until IN2 next touches the component, when it is reported as "changed outside this
+machine's history". And it is a **rebuildable cache**, derived entirely from the evidence bundles:
+losing it loses nothing the bundles cannot re-materialize.
+
+### Rebuilding, and uniting two machines
+
+```
+in2 rebuild-mirror <orgId>                        this machine's bundles only
+in2 rebuild-mirror <orgId> --fetch                also pull other machines' parcels for that org
+in2 rebuild-mirror <orgId> --fetch --batch <id>   fetch under one named batch's grant
+```
+
+A rebuild is always **from scratch, never an append** — which is what lets a foreign wave older than
+everything local take its correct place in history without a merge: the sort key is total, so it
+simply sorts first. A wave present both as a local bundle and as this machine's own uploaded parcel
+is replayed once. Every commit carries a `Materializer:` trailer, and a mirror holding a version
+other than the running build's is reported and fully re-derived rather than appended to.
+
+The result always states its **scope**, because a local-only history and an org-wide one look
+identical from the outside: `--fetch` that could not run (offline, no live grant, route down) is
+never a failure — the rebuild proceeds on local bundles and says that waves run elsewhere are
+absent, and that their absence is not evidence that none exist.
+
+## Rollback
+
+`direct_rollback {sessionId, wave}` undoes a delivered wave, addressed by that rebuild-stable pair
+and never by a SHA. It classifies every selected component before anything runs and changes nothing
+until it is called again with `mode: "execute"`; execution goes through the same apply loop, so a
+rollback earns its own evidence bundle and its commit is marked `Revert-Of: <session>/<wave>`.
+
+**Partial by default** — a component this refuses never blocks the rest of the selection. What each
+class gets: a component the wave *created* is deleted; one it *modified* is restored from the
+bundle's `pre/source/` image (ack-gated when that image declared an unread facet); one it *deleted*
+under 15 days ago is **carded for a Setup undelete, never re-created** — the undelete restores the
+field *and its data*, a re-create restores the definition and destroys every value while reporting
+success; a delete past the window is a re-create behind a per-component ack naming the loss; a
+component that is live again is reported and left alone; and an undo the Metadata API cannot perform
+(a picklist value set moved in either direction, a created RecordType, a granted CMT access) is
+refused, naming the limitation. Acks are one key per component (`ackComponents:
+["CustomField:Account.Region__c"]`) — there is no bulk yes, one key accepts every reason listed
+against that component (the plan prints them all, and says how many the key covers), and a key
+matching no classified component is reported rather than dropped.
+
+**No ack releases an in-window field** (AE4). The class decides that, not the gate: whatever else is
+true of the component — including an R16 divergence, which for a delete means the freed API name has
+been re-occupied — it is carded, and `rollbackWork` throws rather than let one reach the deploy. When
+the preflight does find the name occupied, the card says so, because that is what blocks the
+rename-back after the undelete.
+
+The undelete window is re-checked at execution, per field, and `mode: "verify"` is the wave that
+follows the operator's undelete: it reads the restored field under both its own and its `_del`
+name and diffs it against the wave's pre-image, reporting what the undelete did not restore.
+
+## Read provenance and the contamination report
+
+Every org-reading call appends one record to `<session>/reads.jsonl` — tool, org id, requested
+scope, the component keys it returned (`Type:FullName`), and an **access pattern**: `enumeration`
+(listed the family), `targeted` (named the component), `body` (read its definition). A read whose
+component identity cannot be derived appends an **opaque** record rather than nothing. Identifiers
+only: raw query text stays in `<session>/sf-read/`, and nothing here reaches the event tables.
+
+At batch end that read-set is intersected with what **prior sessions** delivered into the same org,
+per the mirror, and the graded result lands in `<session>/CONTAMINATION.md` (also on demand via
+`direct_history {action: "contamination"}`). It answers measurement validity — did a run scored
+against a corpus read the previous arm's work? — and it is **positive-evidence-only**:
+
+- Enumeration overlap is reported, never as an accusation. Every run lists shared objects.
+- A targeted or body read of a predecessor-delivered component is named individually.
+- The opaque-read count is printed beside every result, because it bounds any claim made from it.
+- An empty mirror reports **"no prior arms recorded on this machine"** — never "clean".
+
+> The certified/compiler tier (14 tools: `compile_requirement`, `lower_contract`,
+> `approve_requirement`, `apply`, `verify`, `record_analysis`, `settle_dispositions`, …) was removed
+> on 2026-07-26 — no users, zero calls in telemetry, and the only reason this package depended on
+> the workspace. Recover from git history if a signed evidence chain is ever genuinely needed.
+
+## Build and test
+
+```bash
+pnpm --filter in2-agent-server build        # tsc -> dist/
+pnpm --filter in2-agent-server test         # vitest
+pnpm --filter in2-agent-server release      # stamp version from the commit, stage payload, npm publish
+pnpm --filter in2-agent-server stage:payload  # just the staging step (skills/agents into the package)
+```
+
+`release` derives the version from the release commit's timestamp (`0.YYYYMMDD.HHMMSS`, semver-legal);
+the repo's `package.json` stays `0.1.0` so a checkout is recognizably not a release. `release:dry`
+does everything but publish.
+
+## Register with Claude Code
+
+Consultant machines never do this by hand — `in2 setup` (from the published package) registers the
+server, sets the env gates on the registration (`CC_MCP_LAUNCH_URL`, `CC_MCP_DIRECT_WRITE=1`,
+`CC_MCP_CAMPFIRE_WRITE=1`, `CC_MCP_BETA=1`, and `CC_MCP_SF_ENTRY` on Windows), installs the skills
+and agents, and probes the server. For a dev checkout, register the built dist directly:
+
+```bash
+claude mcp add cc-mcp --scope user -- node <repo>/apps/cc-mcp-server/dist/index.js
+```
+
+Use an explicit Node **>= 24** binary rather than PATH `node` — Claude Code's PATH may resolve an
+older nvm default, which breaks `project_org`'s live reader (jsforce/undici; live-caught on v20.20.2).
+
+Server env is fixed at spawn, so a gate the run needs must be set **before** the session starts;
+the server logs every gate's state on connect for exactly this reason.
+
+## Safety model
+
+- **Write authority is scoped to the org an activation authenticated.** `CC_MCP_DIRECT_WRITE=1` is a
+  *capability* ("this install may write metadata"), not an *authority* ("to this org"). Authority
+  comes from a grant minted by `activate_session` only after the sf CLI authenticated an org **and**
+  it matched the org the launch service independently named. A grant names one Org ID, is recorded
+  in `direct-write-grants.json` (0600, identity only — never a token), and expires
+  (`CC_MCP_GRANT_TTL_DAYS`, default 30).
+
+  This exists because the alternative does not scale: an Org ID is unknowable until someone logs in,
+  so a customer can never be pre-listed — which pushed internal testing to
+  `CC_MCP_DIRECT_ALLOWLIST=*`. That wildcard makes **every** org the machine's sf CLI holds
+  writable; on a consultant's laptop that includes their own production org and their other
+  clients'. Grants replace it for customers, and the plugin's `run-server.sh` explicitly unsets it.
+
+- **Check order, and it matters:** consultant-org refusal → activation grant → wildcard → env
+  allowlist. The consultant org (VF-partial, `00DRu00000Mpj50MAB`) is refused **first, by Org ID**,
+  so no grant and no allowlist setting can reach it.
+
+- **Campfire writes ride a separate gate.** The consultant org is REAL and SHARED, so
+  `CC_MCP_CAMPFIRE_WRITE` is deliberately distinct from metadata-write authority: permission to
+  deploy to a client org must never imply permission to write the shared org.
+
+- **Fail-closed reads.** An org-read error is never reported as "does not exist" — including a
+  component the org lists but cannot read (orphaned metadata), which records as absent *with a
+  reason* rather than aborting the projection.
+
+- **Idempotent Campfire writes.** Every row is keyed by `External_ID__c`; the batch writer derives
+  each key from the component, so re-running updates instead of duplicating.
+
+- **Observability never participates.** Campfire-started sessions record `batchId` and immutable
+  requirement revision/content hashes, and every reported outcome is read from what the delivery
+  loop already produced. No reporting failure — no database, no grant, no network — can fail a
+  boot, a request, or a tool, and no telemetry code path writes to an org or adds a step to the
+  run. Local evidence remains the authority on what was delivered.
+
+## Operational telemetry
+
+Local timing remains in `.local/cc-mcp/telemetry/<runId>.jsonl`. After a Campfire activation, the
+server also binds `batchId` + install/process/session/version and appends authenticated v2 events to
+`.local/cc-mcp/telemetry-outbox/<runId>.jsonl` before network delivery. The outbox is chmod 600
+where supported, deletes only acknowledged event IDs, and has hard byte/age caps. A
+full/unwritable outbox produces one bounded warning and never blocks a tool.
+
+Four cadences ship it, because a process that dies mid-batch must not take its ledger with it:
+
+- **every 20 seconds**, while the process lives;
+- **at each `deployment.wave_completed`** — a wave boundary is rare and its payload is small, and it
+  is the last durable moment before the org round-trip a run is most likely not to return from;
+- **at `close_batch`**, the explicit end, which now drains the whole outbox rather than sending one
+  200-event batch. A real run emits far more than that, so a single send left the remainder to a
+  timer that was about to stop ticking;
+- **at server start**, which drains whatever a PREVIOUS run stranded on this machine. Everything in
+  the outbox at that instant belongs to a prior process, so the recovery window is the next session
+  on that machine rather than "some later run happens to live long enough for its timer".
+
+Both drains loop past the 200-event delivery cap and stop on the first pass that makes no progress,
+so an unreachable ledger or an expired grant costs exactly one POST. Whatever they could not ship
+stays on disk and is reported — at startup only when something was actually recovered, at close as a
+count of what is still queued, because "could not ship" and "shipped" must not look alike.
+
+Events a run left behind are therefore delayed, not lost. Previously they were durable but nothing
+ever performed the replay, and a killed run's whole batch sat on disk until the age cap dropped it.
+
+The batch-scoped bearer grant is stored separately under
+`.local/cc-mcp/telemetry-grants/<batchId>.json` (chmod 600). It authorizes ingest for one
+batch/install only and is never written to a session, evidence bundle, repository, argv, or log.
+The server stores only its hash. Remote delivery is fail-open; `CC_MCP_TELEMETRY_REMOTE=0` opts out
+without disabling the local timing log.
+
+`scripts/telemetry-report.mjs` accepts either a local JSONL file or the JSON returned by the
+protected central batch-detail endpoint. Agent/operator gap classifications remain estimates: the
+MCP server cannot see exact model time, native client tools, or question-card time.
+
+### The org-call meter
+
+Each `deployment.wave_completed` carries where the wave's **org time** went: `orgCallCount` /
+`orgCallMs`, split by kind into `orgCliCount` / `orgCliMs` and `orgApiCount` / `orgApiMs`, plus
+`orgFirstCallMs` and a per-phase `orgCallsByPhase` (`preProjection`, `postProjection`,
+`preImageRetrieve`, `checkOnly`, `destructiveCheckOnly`, `deploy`, `destructive`, `facetUpdate`,
+`historyProbe`, `changeScan`, `other`).
+
+A Windows run was observed taking up to ~8 minutes per wave against a Mac's ~34s median, and nothing
+in the ledger could apportion it.
+
+**The split by kind is the point.** The intuitive culprit — many expensive `sf` CLI spawns — is not
+what happens: the direct tier spawns `sf` exactly **three** times per wave (retrieve, deploy,
+destructive deploy), the org mirror spawns `git` only, and every projection read goes through
+jsforce, already batched at the API cap of 10 with 5 in flight. A projection makes **tens** of
+round-trips, so counting spawns alone would measure the three cheapest events in the wave. CLI cost
+is process startup — and on Windows an `sf.cmd` shim resolved to its JS entry and run under this
+process's node; API cost is network latency. They have opposite fixes.
+
+**`orgFirstCallMs` separates startup from latency.** A cost concentrated in the first call is
+startup — connection setup, module load, an on-access AV scan of a freshly touched binary. A cost
+spread evenly is latency. Steady state is derivable as `(orgCallMs - orgFirstCallMs) / (orgCallCount
+- 1)`; a first call far above it points at the machine, one in line with it points at the link.
+
+Counts and milliseconds only, and the phase names are a closed set the ingest validator enforces:
+argv and SOQL are where org content lives, and the ledger is shape-only by contract. The meter is
+cleared at each wave's entry, counts failures as well as successes (a call that died still cost the
+wall clock), and excludes the mirror's local git — folding that in would make the number mean two
+things. Absent on a wave that never reached the org, and on installs predating it.
+
+## Provenance parcels
+
+Every wave that changes the org gzips its evidence bundle and the session's `reads.jsonl` into one
+parcel and posts it to `/api/parcel/v1` under the same batch grant telemetry and transcripts use.
+Entries sit at their real session paths (`<sessionId>/direct/<wave>/…`, `<sessionId>/reads.jsonl`)
+so a fetched parcel unpacks exactly where a rebuild expects to find it. **On by default**;
+`CC_MCP_PARCEL_UPLOAD=0` opts out and says so once on stderr.
+
+The client sends exactly one descriptive header, `x-in2-parcel-wave`. It does **not** state the
+org: parcels are fetchable by another machine, so the ledger treats `orgId` as a permission
+boundary and resolves it from the grant's own batch. Org, attempt and verdict travel inside the tar
+in `parcel.json`, which is where a rebuild reads them.
+
+The default is disclosed rather than assumed: most of a parcel restructures content the transcript
+already carries, but `pre/source/` and the pre-image JSON are org state the tools retrieved and the
+model never read, so the install prompt names it explicitly (`startingPrompt` in campfire-launch,
+guarded by a test).
+
+The same two routes read back. `GET /api/parcel/v1` lists what this grant's org holds and
+`GET /api/parcel/v1/blob?parcelId=` returns a short-lived signed URL — again with no org on the way
+out, so the client checks the org the ledger names in the response and skips a grant bound
+elsewhere. `in2 rebuild-mirror <orgId> --fetch` is the consumer: it stages each parcel under
+`.local/cc-mcp/parcel-fetch/<orgId>/` (deliberately **outside** the session workspace, so a fetched
+bundle is never counted as this machine's own work) and hands the unpacked bundle directories to the
+rebuild. The grant is never sent to the storage host the signed URL points at, and every tar entry
+path is checked before a byte is written.
+
+Upload is fail-open in the same sense as the org mirror: the apply loop only awaits the local
+tar-and-spool step, the network flush is fire-and-forget, and nothing here can fail, delay, or mask
+a delivery that landed. Failures land in `.local/cc-mcp/parcel-outbox` (chmod 700, byte/age capped)
+and replay on the next flush — after each wave and once more before the process exits, so a parcel
+does not outlive the grant that is the only thing able to attribute it. A parcel still queued at
+exit gets a line on stderr; one the server permanently rejects is dropped with its reason. Every
+parcel's compressed and raw size is logged and recorded on the wave's verdict, which is the input
+the deferred retention decision needs.
+
+## Env
+
+| Var | Meaning |
+|-----|---------|
+| `CC_MCP_WORKSPACE_ROOT` | Session workspace root (default `<repo>/.local/cc-mcp/sessions`) |
+| `CC_MCP_ORGREPO_ROOT` | Org-mirror root (default `<workspace>/../orgrepo`, i.e. `.local/cc-mcp/orgrepo`) |
+| `CC_MCP_OPERATOR` | Operator identity for the mirror's `Operator:` trailer (default: the session's authenticated username) |
+| `CC_MCP_DIRECT_WRITE` | `1` opens metadata writes (`direct_apply`); consultant org hard-refused regardless |
+| `CC_MCP_DIRECT_ALLOWLIST` | **Internal dev only.** Comma-separated Org IDs (default T-Pinto); `*` allows every authenticated org. Must NOT ship — on a consultant's machine that includes their own production org. Customer installs get authority from an activation grant instead. |
+| `CC_MCP_GRANT_TTL_DAYS` | Lifetime of an activation grant (default 30). A grant outlives a session, not the engagement. |
+| `CC_MCP_CAMPFIRE_WRITE` | `1` opens LIVE writes to the Campfire consultant org |
+| `CC_MCP_CAMPFIRE_ALLOWLIST` | Comma-separated Org IDs allowed for Campfire writes (default VF-partial) |
+| `CC_MCP_TELEMETRY` | `0` disables per-call timing to `.local/cc-mcp/telemetry/<runId>.jsonl` — and, because it short-circuits the whole sink, also stops transcript, parcel, operator-Q&A and beta-feedback upload. One switch, all egress |
+| `CC_MCP_TELEMETRY_REMOTE` | `0` disables durable remote delivery while retaining local timing |
+| `CC_MCP_TRANSCRIPT_UPLOAD` | `0` stops the full Claude Code session text shipping at exit. **On by default**; timings and outcomes still ship |
+| `CC_MCP_PARCEL_UPLOAD` | `0` stops each state-changing wave's provenance parcel shipping — the evidence bundle (including the pre-image the tools retrieved from the org) plus the session's read log. **On by default**; named in the install disclosure |
+| `CC_MCP_OPERATOR_QA_UPLOAD` | `0` sends the transcript without a queryable table of what each question card asked and what the operator answered. **On by default**, and `CC_MCP_TRANSCRIPT_UPLOAD=0` stops it too — the Q&A words are part of the session text that install declined |
+| `CC_MCP_BETA` | `1` turns on the beta feedback channel: registers `report_feedback` and `record_operator_feedback`, and appends a beta section to the supervisor contract. **OFF by default — the one inverted switch in this family**, because an install that never opted in must look exactly like one that predates the feature. `in2 setup` writes it into the registration env, so it travels with the install across `npm install -g` updates |
+| `CC_MCP_FEEDBACK_OUTBOX` | Beta feedback outbox directory (default `.local/cc-mcp/feedback-outbox`) — its own directory beside the telemetry one, which is what keeps a prose record structurally unable to reach the shape-only endpoint |
+| `CC_MCP_PARCEL_OUTBOX` | Parcel outbox directory (default `.local/cc-mcp/parcel-outbox`) |
+| `CC_MCP_PARCEL_STAGE` | Where `rebuild-mirror --fetch` unpacks fetched parcels (default `.local/cc-mcp/parcel-fetch`); kept outside the session workspace on purpose |
+| `CC_MCP_LAUNCH_URL` | Launch origin used for activation and authenticated telemetry delivery — activation + ingest only; release checks go to the npm registry, not here |
+| `CC_MCP_REPO_ROOT` | Override monorepo root resolution (rarely needed) |
+
+## Claude Code harness
+
+`harness/supervisor-playbook.md` is the supervisor workflow and `harness/skills/plan-requirement/SKILL.md` is the
+per-requirement analyzer skill. `pnpm sync:plugin` generates the plugin's copies from these, so the
+harness stays the single source; `pnpm check:plugin` fails when they drift.

package/agents/plan-requirement.md

@@ -0,0 +1,32 @@
+---
+name: plan-requirement
+description: "Analyze ONE Salesforce requirement (or a coupled group, or one fragment of an oversized requirement) against the supervisor's shared projection and analysis brief: decompose it into deliverable components, author the unblocked ones, lint them, and write plan.json. Use for every parallel requirement-analysis Task the IN2 MCP supervisor fans out — REQUIRES the in2 MCP server connected (all org access rides mcp__in2__* tools; there is no Bash). Never use on the bare/CLI harness, whose analyzers need sf + lint.mjs via Bash. Reads the org read-only and never writes to it."
+tools: Read, Write, Edit, Glob, Grep, TodoWrite, mcp__in2__describe_object, mcp__in2__list_components, mcp__in2__sf_read, mcp__in2__direct_lint, mcp__in2__validate_components, mcp__in2__report_feedback
+---
+<!-- GENERATED from apps/cc-mcp-server/harness/agents/plan-requirement.md by scripts/sync-plugin-skills.mjs.
+     source-sha256: 46ae1e6e3df54b5b
+     Edit that source file, then run `npm run sync:plugin`. Do not edit this copy. -->
+
+# IN2 requirement analyzer
+
+Read `skills/plan-requirement/SKILL.md` — it ships with this install at a fixed path and is the
+complete contract for this job. Follow it exactly; nothing below replaces it.
+
+Your Task prompt names the requirement(s) or fragment you own, the session, and the absolute path
+to `analysis/brief.md`. Read your section(s) of the brief FIRST, then the requirement prose.
+
+## Why your tool list is short
+
+You have six IN2 tools and the file tools, and that is deliberate — it is not a restriction added
+on top of the skill, it is the skill's own "Never" list made mechanical:
+
+- `describe_object`, `list_components`, `sf_read` — read the org when the projection falls short.
+- `direct_lint` — lint the files you authored, before you write your plan.
+- `validate_components` — ask the org whether it would ACCEPT what you authored. A checkOnly, so it
+  changes nothing; scoped to the components your own plan.json owns.
+- `report_feedback` — beta installs only; file stumbles before you return.
+
+`project_org`, `direct_apply` and every writer are the supervisor's, after the operator approves.
+You were never permitted to call them, so they are not loaded, and the ~21 tool definitions you
+will never use are not in your context either. If a tool you expected is missing, that is this
+allowlist and not a broken install — say so in your returned summary rather than working around it.

package/dist/campfire/configItem.js

@@ -0,0 +1,201 @@
+// Campfire Configuration Item derivation — the executable form of VFP's
+// "Campfire Configuration Items - Common Types Guide" (v12, 2025-08-08, re-synced against VFP's
+// 2026-08-19 revision; a copy lives at harness/reference/campfire-configuration-items-guide.md).
+//
+// WHY THIS EXISTS: a Configuration Item is not a free-text note, it is a DEPLOYMENT MANIFEST
+// ROW. Campfire composes `ClickDeploy_Text__c` from Type + Configuration Item API Name +
+// Object API Name + Folder API Name, and that text is what gets pasted into ClickDeploy to move
+// the work between orgs. So the fullName the direct tier carries internally
+// ("CF63_Intake_Request__c.CF63_Notes__c", "unfiled$public/My_Template",
+// "Obj__c-My Layout") must be SPLIT into the right fields — writing the composite into the API
+// Name field produces a manifest row that silently fails to resolve in ClickDeploy.
+//
+// Campfire's Type picklist is ALSO not the SDR registry vocabulary: FlexiPage -> LightningPage,
+// CustomApplication -> App, CustomTab -> Tab, WorkflowAlert -> WorkflowEmailAlert,
+// VisualforcePage -> ApexPage, SharingRules -> SharingCriteriaRule | SharingOwnerRule.
+//
+// The mappings below were validated against the org's ACTUAL restricted picklist (vfppartial,
+// 2026-07-25), which corrected the guide's prose in two places: it writes "Approval Process"
+// and "Email Templates", but the only values the picklist accepts are `ApprovalProcess` and
+// `EmailTemplate`. Type__c is RESTRICTED, so a prose-faithful value would have been rejected on
+// save. The picklist also has `Queue`, which the guide never mentions. Where the guide and the
+// org disagree, the ORG wins — it is the thing that has to accept the write.
+// Keyed by the metadata type name the direct tier uses (SDR registry names).
+export const CI_RULES = {
+    // --- object + children -------------------------------------------------------------
+    CustomObject: { campfireType: "CustomObject", shape: "bare", note: "Custom Metadata Types and Custom Settings are ALSO Type=CustomObject." },
+    CustomField: { campfireType: "CustomField", shape: "objectChild", note: "Object API Name may be an object, a __mdt type, or a Custom Setting." },
+    StandardField: { campfireType: "StandardField", shape: "objectChild" },
+    RecordType: { campfireType: "RecordType", shape: "objectChild" },
+    ListView: { campfireType: "ListView", shape: "objectChild" },
+    CompactLayout: { campfireType: "CompactLayout", shape: "objectChild" },
+    ValidationRule: { campfireType: "ValidationRule", shape: "objectChild" },
+    FieldSet: { campfireType: "FieldSet", shape: "objectChild" },
+    WebLink: { campfireType: "WebLink", shape: "objectChild", note: "Custom buttons." },
+    Layout: { campfireType: "Layout", shape: "layout", note: "API Name is the layout's LABEL, not an api name. Package layouts need the package prefix." },
+    // --- actions -----------------------------------------------------------------------
+    QuickAction: {
+        campfireType: "QuickAction",
+        shape: "objectChildOptional",
+        note: "Object-specific action -> Object API Name set. GLOBAL action -> Object API Name must be BLANK."
+    },
+    // --- automation --------------------------------------------------------------------
+    // No static note. "Flows deploy INACTIVE" was printed on every Flow row as though it were a fact
+    // about THIS deployment; CF76 verified both flows landed Active and the note was simply false.
+    // A per-type string can only say what is USUALLY true, and a manifest row is a statement about
+    // what happened. The observed status is read from the bundle's post projection and attached to the
+    // delivery's `deliveredConfiguration` in deriveFromBundle (see observedFlowFacets), where the
+    // description generator projects it — never assumed, and never taken from the submitted XML.
+    Flow: { campfireType: "Flow", shape: "bare" },
+    WorkflowAlert: { campfireType: "WorkflowEmailAlert", shape: "objectChild" },
+    WorkflowFieldUpdate: { campfireType: "WorkflowFieldUpdate", shape: "objectChild" },
+    WorkflowOutboundMessage: { campfireType: "WorkflowOutboundMessage", shape: "objectChild" },
+    WorkflowRule: { campfireType: "WorkflowRule", shape: "objectChild" },
+    WorkflowTask: { campfireType: "WorkflowTask", shape: "objectChild" },
+    AssignmentRule: { campfireType: "AssignmentRule", shape: "objectChild" },
+    ApprovalProcess: {
+        campfireType: "ApprovalProcess",
+        shape: "objectChild",
+        note: "Guide prose says \"Approval Process\" but the restricted picklist value is ApprovalProcess (verified live). Its Workflow Field Updates / Email Alerts must ship in the same deployment."
+    },
+    DuplicateRule: { campfireType: "DuplicateRule", shape: "objectChild" },
+    MatchingRule: { campfireType: "MatchingRule", shape: "objectChild" },
+    // --- metadata records --------------------------------------------------------------
+    CustomMetadata: {
+        campfireType: "CustomMetadata",
+        shape: "objectChild",
+        note: "The RECORD. Object API Name is the __mdt type. (The TYPE itself is Type=CustomObject.) DLRS rollups use Object API Name dlrs__LookupRollupSummary2."
+    },
+    // --- access ------------------------------------------------------------------------
+    PermissionSet: { campfireType: "PermissionSet", shape: "bare" },
+    PermissionSetGroup: { campfireType: "PermissionSetGroup", shape: "bare", note: "Package PSGs need the package prefix." },
+    MutingPermissionSet: { campfireType: "MutingPermissionSet", shape: "bare" },
+    Profile: { campfireType: "Profile", shape: "bare" },
+    CustomPermission: { campfireType: "CustomPermission", shape: "bare" },
+    Group: { campfireType: "Group", shape: "bare", note: "Public groups." },
+    // Live-caught 2026-08-14 (Renner QA, ses_09b70d19): three delivered Roles were dropped from the
+    // writeback because this row was missing — the run called it "a mapping-table gap in my tooling"
+    // and it was. Role IS a legal restricted-picklist value (re-verified live 2026-08-18, 165 values).
+    // VFP's 2026-08-19 guide revision then ADDED a Role section that agrees with this row on both
+    // counts: Type=Role, and "the Role Name" — the field its screenshot rings on the Role Edit page,
+    // which sits beside Label and is the developer name. `bare` + DeveloperName is what they specify.
+    Role: { campfireType: "Role", shape: "bare", note: "The fullName is the role's DeveloperName (e.g. Broker), not its label — the guide's \"Role Name\" field, not the Label beside it." },
+    Queue: { campfireType: "Queue", shape: "bare", note: "Not covered by the guide, but Queue IS a valid Type picklist value (verified live)." },
+    SharingCriteriaRule: { campfireType: "SharingCriteriaRule", shape: "objectChild" },
+    SharingOwnerRule: { campfireType: "SharingOwnerRule", shape: "objectChild" },
+    SharingSet: { campfireType: "SharingSet", shape: "bare" },
+    // --- UI ----------------------------------------------------------------------------
+    CustomTab: { campfireType: "Tab", shape: "bare", note: "Spaces become underscores; a custom-object tab ends in __c." },
+    FlexiPage: { campfireType: "LightningPage", shape: "bare", note: "Lightning Page ASSIGNMENTS are not deployable — ship the App instead." },
+    CustomApplication: { campfireType: "App", shape: "bare", note: "Also the carrier for Lightning Page assignments." },
+    PathAssistant: { campfireType: "PathAssistant", shape: "bare" },
+    UiFormatSpecificationSet: { campfireType: "UiFormatSpecificationSet", shape: "bare", note: "Conditional field formatting." },
+    // --- content / folders --------------------------------------------------------------
+    EmailTemplate: { campfireType: "EmailTemplate", shape: "folderDoc", note: "Guide prose says \"Email Templates\" but the restricted picklist value is EmailTemplate (verified live). Standard public folder is unfiled$public." },
+    EmailTemplateFolder: { campfireType: "EmailTemplateFolder", shape: "bare" },
+    // The SDR registry deploys CLASSIC email folders as type "EmailFolder" — the key direct_apply
+    // records in the evidence bundle — so without this alias the row lands UNMAPPED and forces an
+    // operator round-trip (live-caught SM301: guide + operator resolved it to EmailTemplateFolder;
+    // both EmailFolder and EmailTemplateFolder are legal picklist values, the guide's is used).
+    EmailFolder: { campfireType: "EmailTemplateFolder", shape: "bare" },
+    Report: { campfireType: "Report", shape: "folderDoc", note: "Deploy the folder too." },
+    ReportFolder: { campfireType: "ReportFolder", shape: "bare" },
+    ReportType: { campfireType: "ReportType", shape: "bare" },
+    Dashboard: { campfireType: "Dashboard", shape: "folderDoc", note: "Deploy the folder too." },
+    DashboardFolder: { campfireType: "DashboardFolder", shape: "bare" },
+    // --- integrations -------------------------------------------------------------------
+    // Same Renner QA run dropped a delivered Named Credential for the same reason. NamedCredential
+    // is a legal picklist value (verified live 2026-08-18), and VFP's 2026-08-19 guide revision
+    // added a Named Credential section that specifies exactly this: Type=NamedCredential, API Name =
+    // "The Name of the Named Credential", no Object and no Folder field — i.e. `bare`.
+    //
+    // The guide is still silent on ExternalCredential, and it is NOT in the picklist, so a named
+    // credential's paired external credential still lands unmapped — fail-closed is correct there
+    // until Campfire adds the value AND the guide says how to key it.
+    NamedCredential: { campfireType: "NamedCredential", shape: "bare" },
+    // --- code ---------------------------------------------------------------------------
+    ApexClass: { campfireType: "ApexClass", shape: "bare" },
+    ApexTrigger: { campfireType: "ApexTrigger", shape: "bare" },
+    ApexPage: { campfireType: "ApexPage", shape: "bare", note: "Visualforce pages." },
+    CustomLabel: { campfireType: "CustomLabel", shape: "bare" },
+    CustomNotificationType: { campfireType: "CustomNotificationType", shape: "bare" },
+    GlobalValueSet: { campfireType: "GlobalValueSet", shape: "bare" },
+    StaticResource: { campfireType: "StaticResource", shape: "bare" },
+    Document: { campfireType: "Document", shape: "folderDoc" },
+    DocumentFolder: { campfireType: "DocumentFolder", shape: "bare" }
+};
+const splitFirst = (value, sep) => {
+    const i = value.indexOf(sep);
+    return i < 0 ? null : [value.slice(0, i), value.slice(i + sep.length)];
+};
+// Derive the Campfire CI field set from what the direct tier already knows about a delivered
+// component. Fail-closed: an unmapped type returns an error rather than a guessed Type__c,
+// because a wrong picklist value writes a manifest row that cannot deploy.
+export function deriveConfigItem(typeName, fullName) {
+    const rule = CI_RULES[typeName];
+    if (!rule) {
+        return {
+            error: `No Campfire Configuration Item mapping for metadata type "${typeName}". Campfire's Type picklist is NOT the SDR registry vocabulary — check harness/reference/campfire-configuration-items-guide.md and ask the operator rather than guessing a Type value (a wrong Type produces a ClickDeploy row that will not resolve). Note: Queue is not covered by the guide.`
+        };
+    }
+    const base = { type: rule.campfireType, ...(rule.note ? { note: rule.note } : {}) };
+    switch (rule.shape) {
+        case "bare":
+            return { ...base, apiName: fullName };
+        case "objectChild": {
+            const parts = splitFirst(fullName, ".");
+            if (!parts) {
+                return {
+                    error: `${typeName} "${fullName}" needs an Object.Child fullName — Campfire stores the object in its OWN field (Object API Name) and the child alone in Configuration Item API Name.`
+                };
+            }
+            const [objectApiName, apiName] = parts;
+            // CustomMetadata records: the guide wants the __mdt TYPE in Object API Name, while the
+            // metadata fullName drops the suffix (CF66_Readiness_Rule.Low_Risk).
+            const obj = typeName === "CustomMetadata" && !objectApiName.endsWith("__mdt") ? `${objectApiName}__mdt` : objectApiName;
+            return { ...base, apiName, objectApiName: obj };
+        }
+        case "objectChildOptional": {
+            const parts = splitFirst(fullName, ".");
+            if (!parts)
+                return { ...base, apiName: fullName }; // global action — Object API Name stays blank
+            return { ...base, apiName: parts[1], objectApiName: parts[0] };
+        }
+        case "layout": {
+            const parts = splitFirst(fullName, "-");
+            if (!parts) {
+                return { error: `Layout "${fullName}" needs an "Object-Layout Label" fullName so the object can go in Object API Name.` };
+            }
+            return { ...base, apiName: parts[1], objectApiName: parts[0] };
+        }
+        case "folderDoc": {
+            const parts = splitFirst(fullName, "/");
+            if (!parts) {
+                return {
+                    error: `${typeName} "${fullName}" needs a "Folder/Name" fullName — Campfire stores the folder in Report / Dashboard Folder API Name (use unfiled$public for the standard public folder).`
+                };
+            }
+            return { ...base, apiName: parts[1], folderApiName: parts[0] };
+        }
+    }
+}
+export function isConfigItemError(v) {
+    return "error" in v;
+}
+// Deployment dependencies the guide calls out. These are not deployable facts about ONE
+// component — they are things that must ride along, so they belong on the operator's radar as
+// Deployment Tasks or as extra Configuration Items.
+export const DEPLOYMENT_DEPENDENCY_RULES = [
+    "PermissionSet/Profile granting FLS on a custom field: the field must be in the deployment or already exist in the target org.",
+    "Report/Dashboard: its folder must be deployed too.",
+    "LightningPage embedding a screen flow or list view: that flow/list view must be in the deployment. Certinia components (Cards/Highlights panels) are NOT deployable and must be re-created by hand with the exact same Name.",
+    "Flow referencing custom fields or a custom object: those must be in the deployment or already exist.",
+    "FieldSet: its member fields must be in the deployment or already exist.",
+    "ApprovalProcess: its Workflow Field Updates and Email Alerts must be in the deployment or already exist.",
+    // Not "flows deploy INACTIVE". A Flow deploys with the status its XML DECLARES: author
+    // <status>Active</status> and it lands active, which is what CF76's two flows did while the
+    // manifest and this rule both insisted otherwise. Omit the element and it lands Draft.
+    "Flow: it deploys with the <status> its XML declares — state Active explicitly to have it land active, and verify after deploy, since org settings can still force Draft. Raise an activation Deployment Task only when the deployed status is not Active.",
+    "API-name CHANGES are not deployable: ClickDeploy treats a renamed component as a NEW one and leaves the original behind.",
+    "Certinia data-backed components (navigation menus, card panels, highlights) are data, not metadata — track them as a Pre-Deployment Deployment Task and move them by data export/import."
+];