in2-agent-server 0.20260821.185429

package/dist/projection/project.js

@@ -0,0 +1,214 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { readCustomFieldSnapshot, readGenericMetadataSnapshot, readLayoutSnapshot } from "./bridge.js";
+import { resolveScope } from "./scope.js";
+import { collectPrecedentComponents, probeOrgTraits } from "./precedent.js";
+import { checkScopeNameAmbiguity } from "./nameAmbiguity.js";
+import { renderMap } from "./mapmd.js";
+function safeName(value) {
+    return value.replace(/[^A-Za-z0-9_.-]/g, "_");
+}
+async function writeSnapshot(outDir, relFile, snap) {
+    const abs = path.join(outDir, relFile);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, `${JSON.stringify(snap, null, 2)}\n`, "utf8");
+}
+// A projection that resolves to hundreds of components is almost never what was intended; it is
+// what happens when a standard object gets added to scope "to be safe". Account and Contact carry
+// hundreds of custom fields on any real org, and each one is a component. The cost is invisible at
+// the call site — the scope reads as five objects — which is exactly why this refuses rather than
+// warns. Batching made the pathological case survivable; it did not make it correct.
+export class ScopeTooLargeError extends Error {
+    total;
+    limit;
+    breakdown;
+    constructor(total, limit, breakdown) {
+        super(`scope resolves to ${total} components (limit ${limit})`);
+        this.total = total;
+        this.limit = limit;
+        this.breakdown = breakdown;
+    }
+}
+export const DEFAULT_MAX_COMPONENTS = 250;
+export async function runProjection(reader, opts) {
+    const readField = opts.readField ?? readCustomFieldSnapshot;
+    const readGeneric = opts.readGeneric ?? readGenericMetadataSnapshot;
+    const readLayout = opts.readLayout ?? readLayoutSnapshot;
+    // A projection is a point-in-time read, so it starts from nothing cached. This belongs HERE and
+    // not at the one call site that noticed the problem: any caller reusing a reader across two
+    // projections would otherwise get the first one's answers for the second one's question, and
+    // direct_apply — which reads before and after a deploy through one reader — is simply the case
+    // where that is most obviously wrong.
+    reader.invalidate?.();
+    const identity = await reader.identity();
+    const resolved = await resolveScope(reader, opts.scope);
+    const limit = opts.maxComponents ?? DEFAULT_MAX_COMPONENTS;
+    const total = resolved.components.length +
+        resolved.objects.reduce((n, p) => n + 1 + p.customFields.length + p.validationRules.length, 0);
+    if (total > limit) {
+        throw new ScopeTooLargeError(total, limit, resolved.objects
+            .map((p) => ({ objectApiName: p.objectApiName, customFields: p.customFields.length }))
+            .sort((a, b) => b.customFields - a.customFields));
+    }
+    // AMBIGUITY, checked against the CALLER'S components and before precedent adds any of its own.
+    // A projection reads the name it was given and records the answer; when two components in the org
+    // answer to that name, the choice was made silently and the manifest is where it has to surface.
+    const scopeAmbiguities = await checkScopeNameAmbiguity(reader, resolved.components).catch(() => []);
+    // PRECEDENT + ORG TRAITS, gathered AFTER the caller's scope has been size-checked so they can
+    // neither inflate the operator's cap nor trip ScopeTooLargeError on work they did not ask for.
+    // Both are best-effort: a failure here leaves the projection exactly as it would have been.
+    const traits = await probeOrgTraits(reader).catch(() => ({ multiCurrency: false, personAccounts: false, callCenter: false, notes: ["org-trait probe failed"] }));
+    // Concrete evidence beats the probe: CurrencyIsoCode exists as a standard field ONLY on a
+    // multi-currency org, and the scope resolution has already enumerated standard fields. A probe
+    // that says "no" beside a field list that says otherwise is how CF79 shipped a MAP whose trait
+    // line contradicted its own page — and the trait exists precisely to stop an authored Layout
+    // from dropping CurrencyIsoCode.
+    if (!traits.multiCurrency && resolved.objects.some((o) => o.standardFields.some((f) => f.name === "CurrencyIsoCode"))) {
+        traits.multiCurrency = true;
+        traits.notes.push("multi-currency: probe said no, but CurrencyIsoCode exists on a projected object — field evidence wins");
+    }
+    const precedent = opts.skipPrecedent
+        ? []
+        : await collectPrecedentComponents(reader, resolved.components).catch(() => []);
+    // MARKED, not just appended. Downstream these are indistinguishable from the caller's own scope
+    // unless the manifest says so, and at least one consumer must never confuse the two: the org
+    // mirror records what a wave DELIVERED, and it reads the wave's post manifest to find out. A
+    // sample that reads as a delivery becomes a claim about somebody's work — see
+    // ManifestComponent.precedent for the live case.
+    const precedentKeys = new Set(precedent.map((c) => `${c.typeName}:${c.fullName}`));
+    resolved.components.push(...precedent);
+    // Warm every read this run is about to perform, batched ten-per-call and five calls in flight,
+    // BEFORE the sequential walk below. The walk stays sequential on purpose — it writes files and
+    // appends to `components`, so its ordering is what makes the manifest deterministic — but by the
+    // time it runs, each read is a cache hit rather than a SOAP round-trip.
+    //
+    // This is the whole fix for a projection scoped to standard objects. Account + Contact resolve to
+    // ~490 custom fields; one round-trip each ran past five minutes with no output and read as a
+    // hang. Batched, that is ~49 calls.
+    await reader.prefetch?.([
+        { typeName: "CustomObject", fullNames: resolved.objects.map((p) => p.objectApiName) },
+        {
+            typeName: "CustomField",
+            fullNames: [
+                ...resolved.objects.flatMap((p) => p.customFields.map((f) => `${p.objectApiName}.${f}`)),
+                ...resolved.components.filter((c) => c.typeName === "CustomField").map((c) => c.fullName)
+            ]
+        },
+        {
+            typeName: "ValidationRule",
+            fullNames: resolved.objects.flatMap((p) => p.validationRules.map((r) => `${p.objectApiName}.${r}`))
+        },
+        ...Object.entries(resolved.components
+            .filter((c) => c.typeName !== "CustomField")
+            .reduce((acc, c) => {
+            (acc[c.typeName] ??= []).push(c.fullName);
+            return acc;
+        }, {})).map(([typeName, fullNames]) => ({ typeName, fullNames }))
+    ]);
+    const components = [];
+    const byFile = new Map();
+    // Scoped to THIS run for the same reason the reader's cache is (see reader.invalidate above): a
+    // projection is a point-in-time read, and layouts that come and go between runs must not be
+    // answered from a previous one.
+    const layoutRows = new Map();
+    const record = async (typeName, fullName, relFile, snap) => {
+        await writeSnapshot(opts.outDir, relFile, snap);
+        byFile.set(relFile, snap);
+        const found = snap.state.metadata !== null;
+        components.push({
+            typeName,
+            fullName,
+            file: relFile,
+            found,
+            ...(precedentKeys.has(`${typeName}:${fullName}`) ? { precedent: true } : {}),
+            // Fail-closed visibility: a read error is never rendered as clean absence.
+            ...(snap.errors?.length ? { errors: snap.errors } : found ? {} : { errors: ["not found"] })
+        });
+    };
+    for (const plan of resolved.objects) {
+        const objDir = path.join("objects", safeName(plan.objectApiName));
+        const objSnap = (await readGeneric(reader, "customObject", "CustomObject", plan.objectApiName));
+        await record("CustomObject", plan.objectApiName, path.join(objDir, "object.json"), objSnap);
+        for (const field of plan.customFields) {
+            const fullName = `${plan.objectApiName}.${field}`;
+            const snap = (await readField(reader, fullName));
+            await record("CustomField", fullName, path.join(objDir, "fields", `${safeName(field)}.json`), snap);
+        }
+        for (const rule of plan.validationRules) {
+            const fullName = `${plan.objectApiName}.${rule}`;
+            const snap = (await readGeneric(reader, "validationRule", "ValidationRule", fullName));
+            await record("ValidationRule", fullName, path.join(objDir, "validation-rules", `${safeName(rule)}.json`), snap);
+        }
+    }
+    for (const component of resolved.components) {
+        const relFile = path.join("components", safeName(component.typeName), `${safeName(component.fullName)}.json`);
+        try {
+            // Layout gets a DEDICATED reader for the same reason CustomField does: the generic
+            // metadata.read is not a faithful source for one of its facets. See orgread/layoutSnapshot.ts
+            // — SOAP readMetadata silently omits related lists and jsforce renders the absence as `[]`,
+            // which on a full-file-replace type reads as a licence to delete them.
+            const snap = component.typeName === "CustomField"
+                ? (await readField(reader, component.fullName))
+                : component.typeName === "Layout"
+                    ? (await readLayout(reader, component.fullName, layoutRows))
+                    : (await readGeneric(reader, "generic", component.typeName, component.fullName));
+            await record(component.typeName, component.fullName, relFile, snap);
+        }
+        catch (error) {
+            // ONE unreadable component must not abort the whole projection. Live-caught: an org listed
+            // ApprovalProcess:SCMC__Purchase_Order__c.POApprove whose parent object no longer exists —
+            // orphaned metadata left behind by an uninstalled managed package. Salesforce does not return
+            // found:false for that, it throws a SOAP fault ("Entity 'null' not found"), which killed a
+            // three-component projection over one dead component. Any mature org accumulates these.
+            //
+            // Recorded as a per-component error instead, which is how every other read failure in this
+            // file already behaves — the component reads as absent WITH a reason, and the manifest's
+            // error count reflects it. Still fail-closed: absent-with-an-error is never mistaken for
+            // verified-absent, because callers check errors before treating a miss as truth.
+            await record(component.typeName, component.fullName, relFile, {
+                family: "generic",
+                typeName: component.typeName,
+                fullName: component.fullName,
+                observedAt: new Date().toISOString(),
+                source: "metadata.read",
+                state: { metadata: null },
+                errors: [
+                    `read failed: ${error instanceof Error ? error.message : String(error)} — the component is listed by the org but could not be read. A common cause is orphaned metadata whose parent object no longer exists.`
+                ]
+            });
+        }
+    }
+    const manifest = {
+        schemaVersion: "org-projection-v1",
+        orgAlias: opts.orgAlias,
+        orgId: identity.orgId,
+        apiVersion: opts.apiVersion,
+        label: opts.label,
+        createdAt: new Date().toISOString(),
+        scope: opts.scope,
+        reader: "cc-mcp orgread: SalesforceOrgReader + snapshot readers (ported from sf-config-verifier)",
+        components,
+        objects: resolved.objects.map((plan) => ({
+            objectApiName: plan.objectApiName,
+            standardFields: plan.standardFields,
+            layouts: plan.layouts,
+            errors: plan.errors
+        })),
+        enumerationErrors: resolved.errors,
+        orgTraits: traits,
+        // Omitted when empty on purpose — see ProjectionManifest.scopeAmbiguities. A best-effort check
+        // that reported `[]` would be claiming it looked and found nothing, which it cannot promise.
+        ...(scopeAmbiguities.length ? { scopeAmbiguities } : {}),
+        counts: {
+            components: components.length,
+            errors: components.filter((c) => c.errors?.length).length +
+                resolved.errors.length +
+                resolved.objects.reduce((n, o) => n + o.errors.length, 0)
+        }
+    };
+    const mapMarkdown = renderMap(manifest, byFile);
+    await fs.mkdir(opts.outDir, { recursive: true });
+    await fs.writeFile(path.join(opts.outDir, "projection.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    await fs.writeFile(path.join(opts.outDir, "MAP.md"), mapMarkdown, "utf8");
+    return { manifest, mapMarkdown, byFile };
+}

package/dist/projection/scope.js

@@ -0,0 +1,110 @@
+function soqlQuote(value) {
+    return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+// Live-caught (T-Pinto, 2026-07-22): Tooling-API EntityDefinition does NOT honor \_
+// escaping in LIKE — the escaped pattern matches nothing. So the query deliberately
+// OVER-matches (wildcards left live) and the exact prefix is enforced client-side,
+// which also drops the platform-derived entities (__Share/__ChangeEvent/...) the
+// wildcard sweeps in.
+const PROJECTABLE_OBJECT_RE = /__(c|mdt)$/;
+const CUSTOM_FIELD_RE = /__(c|pc)$/i;
+export function scopeIsEmpty(scope) {
+    return ((scope.objects?.length ?? 0) === 0 &&
+        !(scope.prefix && scope.prefix.trim()) &&
+        (scope.components?.length ?? 0) === 0);
+}
+async function planObject(reader, objectApiName) {
+    const plan = {
+        objectApiName,
+        customFields: [],
+        standardFields: [],
+        validationRules: [],
+        layouts: [],
+        errors: []
+    };
+    const quoted = soqlQuote(objectApiName);
+    try {
+        const fields = await reader.toolingQuery(`SELECT QualifiedApiName, DataType FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = '${quoted}'`);
+        for (const f of fields.records) {
+            if (CUSTOM_FIELD_RE.test(f.QualifiedApiName))
+                plan.customFields.push(f.QualifiedApiName);
+            else
+                plan.standardFields.push({ name: f.QualifiedApiName, dataType: f.DataType });
+        }
+        plan.customFields.sort();
+        plan.standardFields.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch (error) {
+        plan.errors.push(`field enumeration failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        const rules = await reader.toolingQuery(`SELECT ValidationName FROM ValidationRule WHERE EntityDefinition.QualifiedApiName = '${quoted}'`);
+        plan.validationRules = rules.records.map((r) => r.ValidationName).sort();
+    }
+    catch (error) {
+        plan.errors.push(`validation-rule enumeration failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        // Layout.TableEnumOrId holds the object NAME for standard objects and the object ID
+        // for custom objects — resolve the DurableId for the custom case.
+        let tableKey = objectApiName;
+        if (/__c$/i.test(objectApiName)) {
+            const entity = await reader.toolingQuery(`SELECT DurableId FROM EntityDefinition WHERE QualifiedApiName = '${quoted}'`);
+            const durable = entity.records[0]?.DurableId;
+            if (!durable)
+                throw new Error(`EntityDefinition DurableId not found for ${objectApiName}`);
+            tableKey = durable;
+        }
+        const layouts = await reader.toolingQuery(`SELECT Name FROM Layout WHERE TableEnumOrId = '${soqlQuote(tableKey)}'`);
+        plan.layouts = layouts.records.map((l) => l.Name).sort();
+    }
+    catch (error) {
+        plan.errors.push(`layout enumeration failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return plan;
+}
+export async function resolveScope(reader, scope) {
+    const errors = [];
+    const objectNames = new Set(scope.objects ?? []);
+    if (scope.prefix && scope.prefix.trim()) {
+        const prefix = scope.prefix.trim();
+        try {
+            const rows = await reader.toolingQuery(`SELECT QualifiedApiName FROM EntityDefinition WHERE QualifiedApiName LIKE '${soqlQuote(prefix)}%'`);
+            const matched = rows.records
+                .map((r) => r.QualifiedApiName)
+                .filter((name) => name.startsWith(prefix) && PROJECTABLE_OBJECT_RE.test(name));
+            for (const name of matched)
+                objectNames.add(name);
+            if (matched.length === 0) {
+                errors.push(`prefix '${prefix}' matched no projectable objects (__c/__mdt)`);
+            }
+        }
+        catch (error) {
+            errors.push(`prefix enumeration failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const objects = [];
+    for (const name of [...objectNames].sort()) {
+        objects.push(await planObject(reader, name));
+    }
+    // Explicit components, deduped against object expansion output (by type+fullName).
+    const covered = new Set();
+    for (const plan of objects) {
+        covered.add(`CustomObject:${plan.objectApiName}`);
+        for (const f of plan.customFields)
+            covered.add(`CustomField:${plan.objectApiName}.${f}`);
+        for (const r of plan.validationRules)
+            covered.add(`ValidationRule:${plan.objectApiName}.${r}`);
+    }
+    const components = [];
+    const seen = new Set();
+    for (const c of scope.components ?? []) {
+        const key = `${c.typeName}:${c.fullName}`;
+        if (covered.has(key) || seen.has(key))
+            continue;
+        seen.add(key);
+        components.push({ typeName: c.typeName, fullName: c.fullName });
+    }
+    components.sort((a, b) => `${a.typeName}:${a.fullName}`.localeCompare(`${b.typeName}:${b.fullName}`));
+    return { objects, components, errors };
+}

package/dist/projection/types.js

@@ -0,0 +1,5 @@
+// Org projection (plan 2026-07-22-001, Phase 1). Structural types only — the live
+// implementations come from the verifier (the independent read path), imported via
+// the ambient declarations in verifier.d.ts so the projection shows the org exactly
+// as the gate sees it. No third read path.
+export {};

package/dist/tools/analyze.js

@@ -0,0 +1,322 @@
+// resolve_blocker — close an answered blocker without re-running an analyzer.
+//
+// WHAT USED TO LIVE HERE, AND WHY IT DOES NOT
+//
+// analyzer_briefs returned one ready-to-launch prompt per requirement. It solved a real problem —
+// the supervisor had been inlining a 7 KB skill into every prompt — but it solved it by moving the
+// same large text one hop: the tool emitted the prompts and the supervisor echoed them back
+// verbatim into its Agent calls, so the whole thing crossed the wire twice. Six calls across four
+// runs, and the file it pointed at was already on disk at a fixed path the whole time.
+//
+// The subagent call is now just: read <skill path>, you own REQ-X, plus the two or three sentences
+// of cross-requirement context that were ever actually dynamic. No tool needed to say that.
+//
+// ORIGINAL NOTE, kept because the constraint it records still holds
+//
+// Step 3 of the loop is "one analyzer subagent per requirement", and the harness told the
+// supervisor to compose each prompt itself, carrying the FULL plan-requirement SKILL.md inline plus
+// the paths plus the batch context. That is ~7.4 KB of skill text per requirement, authored N times,
+// before a single analyzer starts. On a 15-requirement batch it is the largest block of writing in
+// the whole run, it is nearly identical every time, and every variation in it is a way for one
+// analyzer to be told something subtly different from its siblings.
+//
+// It also could not work on a real install: the skill lives in the repo, and until now nothing
+// shipped it in the download. A consultant's machine had no SKILL.md to inline — the same failure
+// class as check_components pointing at an unbuilt workspace package.
+//
+// So the server emits ready-to-launch briefs. It already knows the session, the requirements, the
+// session directory layout and the projection dirs; the only thing it does not know is the
+// cross-requirement context the supervisor formed by reading the batch, which is exactly what the
+// `context` parameter is for. The brief POINTS at the skill rather than inlining it, so each
+// analyzer reads one file from disk instead of receiving a copy through the prompt.
+//
+// ADDRESSING UNDER THE REVISION MODEL
+//
+// `promote` and `drop` used to address entries by `typeName:fullName` and act on every match. That
+// was total while a key meant exactly one entry. Once a batch can change a component twice — a
+// `create` in the requirement that brings it into being, an `update` in the one that adjusts it,
+// each bound to its own authored file — the same bare key names TWO entries, and the old loop
+// would have dropped the create along with the update, silently, in the file Configuration Item
+// ownership is derived from.
+//
+// So an operation may name the revision as `{key, path}`, matched against the entry's
+// `authoredFile`, and a bare key on a multi-entry component REFUSES (`AMBIGUOUS_COMPONENT`) rather
+// than acting on both. A bare key on a single-entry component is the whole address, exactly as
+// before — which is every plan written before the revision model and most entries after it.
+//
+// The read-modify-write also stopped being an untyped `Record` round trip: it goes through
+// `core/planFile.ts`, which returns the parsed document unchanged where nothing edited it. That
+// module was built for this call — its mutators take an ENTRY, not a key, for the reason above.
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+import { clearProvisional, readPlanFile, removeEntry, serializePlanFile } from "../core/planFile.js";
+import { fail, internalError, ok } from "../core/result.js";
+import { WorkspaceError, sessionDir } from "../core/workspace.js";
+/**
+ * One `promote`/`drop` target.
+ *
+ * The bare-string form is kept because it is the right address for a single-entry key and because
+ * every existing caller (and the playbook's own `promote: ["<key>"]`) writes it. The object form
+ * exists only for the case the string form cannot express: which of a component's revisions.
+ *
+ * A FACTORY, not a shared constant: `promote` and `drop` both use it, and zod-to-json-schema
+ * collapses a reused instance into a `$ref` at the second use site (`#/properties/promote/items`).
+ * Legal JSON Schema, but a pointer is a worse thing to hand a model than the shape itself, and
+ * strict tool-schema consumers do not all resolve internal refs. Two calls, two inlined copies.
+ */
+const operationSchema = () => z.union([
+    z.string().describe("Component key, e.g. CustomField:X__c.Days__c."),
+    z.object({
+        key: z.string().describe("Component key, e.g. CustomField:X__c.Days__c."),
+        path: z
+            .string()
+            .optional()
+            .describe("WHICH revision, for a component this batch changes more than once. Matched against the entry's `authoredFile` (relative to requirements/<extId>/authored/). Only needed when the key has more than one entry — a bare key then refuses rather than hitting both."),
+        intent: z
+            .enum(["create", "update", "delete"])
+            .optional()
+            .describe("WHICH revision, by what it does. This is how you name a `delete` entry, which has no authoredFile for `path` to match — use it when the operator holds back a deletion that rides beside a state this requirement also deploys.")
+    })
+]);
+const opKey = (op) => (typeof op === "string" ? op : op.key);
+const opPath = (op) => (typeof op === "string" ? undefined : op.path);
+const opIntent = (op) => (typeof op === "string" ? undefined : op.intent);
+/** Separator-normalized comparison, matching how the wave assembler matches its own `path`. */
+const normRel = (value) => value.split(/[\\/]/).filter(Boolean).join("/");
+const opLabel = (op) => {
+    const bound = opPath(op);
+    const intent = opIntent(op);
+    const parts = [bound ? normRel(bound) : undefined, intent ? `intent: ${intent}` : undefined].filter(Boolean);
+    return parts.length > 0 ? `${opKey(op)} (${parts.join(", ")})` : opKey(op);
+};
+/**
+ * Address one operation at one entry.
+ *
+ * Matches over ALL entries for the key, including `deployable: false` routes: the hazard this
+ * guards is "one call changed two entries", and a route entry is still an entry someone can mean.
+ */
+function resolveOperation(plan, verb, op) {
+    const key = opKey(op);
+    const bound = opPath(op);
+    const forKey = plan.entries.filter((e) => e.key === key);
+    if (forKey.length === 0)
+        return { kind: "unknown", verb, op };
+    const intent = opIntent(op);
+    // BOTH discriminators, and both are needed. `path` tells two deployed states apart, and it is the
+    // only thing that can — but a `delete` entry has no authoredFile by construction, so `path` can
+    // never name one. Without `intent`, a requirement that both changes and retires its own component
+    // would carry a deletion nobody could drop: the bare key refuses as ambiguous and no path matches.
+    // Dropping a held-back deletion is exactly the operation the live plan prescribed for itself.
+    let matches = forKey;
+    if (bound !== undefined)
+        matches = matches.filter((e) => e.authoredFile !== null && normRel(e.authoredFile) === normRel(bound));
+    if (intent !== undefined)
+        matches = matches.filter((e) => e.intent === intent);
+    if (matches.length === 0)
+        return { kind: "unknown", verb, op };
+    if (matches.length > 1)
+        return { kind: "ambiguous", verb, op, entries: matches };
+    return { kind: "hit", verb, op, entry: matches[0] };
+}
+/** `intent=create authoredFile=…` — enough to tell two revisions of one component apart. */
+const describeEntry = (entry) => `entry ${entry.index}: intent=${entry.intent ?? "(undeclared)"} authoredFile=${entry.authoredFile ?? "(none)"}`;
+export function registerAnalyzeTools(server) {
+    server.registerTool("resolve_blocker", {
+        title: "Record an operator answer against an analyzer's blocker",
+        description: "Close a blocker in requirements/<extId>/plan.json with the operator's answer, WITHOUT re-running the analyzer. Use when the answer changes a detail you can edit yourself — a picklist default, an element value, a label. " +
+            "EDIT THE ANALYZER'S FILE under requirements/<extId>/authored/, never the assembled wave tree: direct_lint/direct_apply rebuild that tree on every call, so an edit made inside it is silently overwritten rather than deployed. Nothing checks this. " +
+            "Re-run the analyzer instead when the answer changes WHICH components exist or who owns them — that is a different plan, not an edit. " +
+            "A component can also be provisional on ANOTHER requirement's blocker: omit blockerId and pass `reason` naming that decision, and promote/drop reconcile THIS plan without inventing a local blocker. Refuses on `REASON_REQUIRED` / `NOTHING_TO_RECONCILE`. " +
+            "ADDRESSING: a component this batch changes twice has two entries under one key, so name the revision as {key, path} on promote/drop; a bare key refuses (`AMBIGUOUS_COMPONENT`). A DELETE entry has no authoredFile — name it {key, intent: 'delete'}, which is how a decision to HOLD a deletion is recorded before the Campfire writeback reports it as work.",
+        inputSchema: {
+            sessionId: z.string().describe("The session the plan belongs to."),
+            extId: z.string().describe("Requirement whose blocker this answers, e.g. REQ-15462."),
+            blockerId: z
+                .string()
+                .optional()
+                .describe("Blocker id from plan.json, e.g. B1. OMIT when the gating decision lives on another requirement's blocker — then `reason` is required and promote/drop reconcile this plan directly."),
+            answer: z.string().optional().describe("The operator's answer, verbatim. Recorded so the plan states what was decided, not merely that something was. Required with blockerId."),
+            reason: z
+                .string()
+                .optional()
+                .describe("Required when blockerId is omitted: which decision settles this reconciliation, e.g. \"REQ-15519 B1 resolved: OWD Private — the condition this component was provisional on\". Recorded on the plan as a reconciliation entry."),
+            amended: z
+                .array(z.string())
+                .optional()
+                .describe("Component keys you edited as a result, e.g. [\"CustomField:CF75_Intake_Request__c.CF75_Days_Remaining__c\"]. Recorded on the plan so the change is attributable."),
+            promote: z
+                .array(operationSchema())
+                .optional()
+                .describe("Components whose PROVISIONAL authored file the answer confirms — a key, or {key, path} to name ONE revision. Clears `provisional`, which is what wave assembly gates on (`COMPONENT_STILL_PROVISIONAL`)."),
+            drop: z
+                .array(operationSchema())
+                .optional()
+                .describe("Components the answer ELIMINATED — a key, or {key, path} to remove ONE revision and leave the other. Removes the entry from plan.json entirely, so plan_waves stops ordering a wave that assembles nothing for it.")
+        }
+    }, async ({ sessionId, extId, blockerId, answer, reason, amended, promote, drop }) => {
+        try {
+            const file = path.join(sessionDir(sessionId), "requirements", extId, "plan.json");
+            // One reader for this schema (`core/planFile.ts`), and it hands back the document it parsed
+            // so the write half round-trips: fields this tool has never heard of survive, and a plan
+            // nothing edited is rewritten byte-for-byte. Structural refusals come back as DATA and are
+            // deliberately not fatal here — a plan whose bindings are wrong is exactly the plan the
+            // operator uses this tool to FIX, while the assembler and plan_waves refuse on the finding.
+            const read = await readPlanFile(file, extId);
+            if (!read.ok)
+                return fail(read.error.code, read.error.message);
+            const plan = read.plan;
+            const blockers = Array.isArray(plan.document.blockers) ? plan.document.blockers : [];
+            let blocker;
+            if (blockerId !== undefined) {
+                if (!answer)
+                    return fail("ANSWER_REQUIRED", `Resolving ${extId} blocker ${blockerId} needs the operator's answer verbatim.`);
+                blocker = blockers.find((b) => String(b.id) === blockerId);
+                // Fail-closed: silently accepting an unknown id would report a question as settled while it
+                // is still open, and the approval card is built from exactly this record.
+                if (!blocker) {
+                    return fail("BLOCKER_NOT_FOUND", `${extId} has no blocker "${blockerId}". Open blockers: ${blockers.map((b) => String(b.id)).join(", ") || "(none)"}.`);
+                }
+                if (blocker.resolved) {
+                    return fail("BLOCKER_ALREADY_RESOLVED", `${extId} blocker ${blockerId} is already answered: "${String(blocker.answer ?? "")}". Recording a second answer would lose the first; correct the plan by hand if it is wrong.`);
+                }
+            }
+            else {
+                // No local blocker: this is a reconciliation driven by a decision recorded ELSEWHERE
+                // (typically another requirement's blocker — live: CF79's sharing rule was provisional
+                // on the object owner's OWD answer, and the only way to promote it was hand-editing
+                // plan.json). Fail-closed on a missing reason or an empty reconciliation: a promote with
+                // no recorded cause is exactly the unattributable hand-edit this tool exists to replace.
+                if (!reason) {
+                    return fail("REASON_REQUIRED", `Without a blockerId, pass \`reason\` naming the decision that settles this reconciliation (e.g. the other requirement's resolved blocker).`);
+                }
+                if (!promote?.length && !drop?.length) {
+                    return fail("NOTHING_TO_RECONCILE", `Without a blockerId, pass promote and/or drop — a reason alone changes nothing.`);
+                }
+            }
+            // RECONCILE THE PLAN, not just the blocker. An answer routinely settles which components
+            // exist and which authored draft is the right one, and until now the only way to record
+            // that was to hand-edit plan.json — the file Configuration Item ownership is derived from.
+            // Editing it by hand is how plans drift, and a stale entry propagates: plan_waves orders a
+            // component nobody will author, and the wave then assembles nothing for it.
+            //
+            // RESOLVE EVERY OPERATION BEFORE CHANGING ANYTHING. Both refusals below promise "Nothing
+            // was changed"; addressing first is what makes that true of the in-memory document as well
+            // as the file, so a half-applied reconcile cannot exist even transiently.
+            const componentCount = () => (Array.isArray(plan.document.components) ? plan.document.components.length : 0);
+            const before = componentCount();
+            const resolved = [
+                ...(drop ?? []).map((op) => resolveOperation(plan, "drop", op)),
+                ...(promote ?? []).map((op) => resolveOperation(plan, "promote", op))
+            ];
+            // The addressing context of THIS call, fixed before any drop changes it: which keys carry
+            // more than one entry, and therefore which reports have to name a file to mean anything.
+            const multiEntryKeys = new Set(plan.entries.filter((e, _i, all) => all.filter((o) => o.key === e.key).length > 1).map((e) => e.key));
+            // On a multi-entry key the key alone no longer says WHICH revision this touched. The file is
+            // the usual discriminator; a delete has none, so it is named by what it does — the report has
+            // to be readable as a record of "the deletion was dropped", not "something with no file was".
+            const entryLabel = (entry) => multiEntryKeys.has(entry.key)
+                ? `${entry.key} (${entry.authoredFile ?? (entry.intent === "delete" ? "intent: delete, no authoredFile" : "no authoredFile")})`
+                : entry.key;
+            // Checked BEFORE the unknown-key refusal: a bare key on two revisions is the more specific
+            // finding, and its remediation is the one the caller cannot guess.
+            const ambiguous = resolved.filter((r) => r.kind === "ambiguous");
+            if (ambiguous.length > 0) {
+                const first = ambiguous[0];
+                const example = first.entries.find((e) => e.authoredFile !== null) ?? first.entries[0];
+                return fail("AMBIGUOUS_COMPONENT", [
+                    `${extId}'s plan.json holds more than one entry — two states of one component — for a component named by key alone.`,
+                    "Acting on the key would hit EVERY revision of it: a drop would delete the create as well as the update.",
+                    ...ambiguous.flatMap((a) => [
+                        `  ${a.verb} ${opKey(a.op)} matches ${a.entries.length} entries:`,
+                        ...a.entries.map((e) => `    ${describeEntry(e)}`)
+                    ]),
+                    "",
+                    "Name the revision by the file it is bound to, e.g.",
+                    `  ${first.verb}: [{ "key": ${JSON.stringify(opKey(first.op))}, "path": ${JSON.stringify(example.authoredFile ?? "<the entry's authoredFile>")} }]`,
+                    "Nothing was changed."
+                ].join("\n"));
+            }
+            // Fail-closed on a key that matches nothing: silently ignoring it would report the plan as
+            // reconciled while leaving the component exactly as it was. The "Present:" listing names
+            // each entry's bound file where a key carries more than one, so a caller who addressed the
+            // wrong revision can see which one they meant.
+            const unknown = resolved.filter((r) => r.kind === "unknown");
+            if (unknown.length > 0) {
+                const present = plan.entries.map(entryLabel).join(", ") || "(none)";
+                return fail("COMPONENT_NOT_IN_PLAN", `${extId}'s plan.json has no component(s): ${unknown.map((u) => opLabel(u.op)).join(", ")}. Present: ${present}. Nothing was changed.`);
+            }
+            // ONE ENTRY, ONE OPERATION. Naming the same revision twice — `drop` and `promote` on one
+            // entry, or the same key listed twice — used to produce a report claiming both happened
+            // when only one could: the promote clears a flag on a node the drop already detached from
+            // the document, so the plan says one thing and the answer says another.
+            const hits = resolved.filter((r) => r.kind === "hit");
+            const collided = hits.filter((r, i) => hits.some((other, j) => j !== i && other.entry === r.entry));
+            if (collided.length > 0) {
+                return fail("CONFLICTING_OPERATIONS", [
+                    `${extId}: the same plan entry is named by more than one operation, so this call would report changes it cannot all make.`,
+                    ...[...new Set(collided.map((r) => r.entry))].map((entry) => `  ${entry.key} ${describeEntry(entry)} — named by ${collided.filter((r) => r.entry === entry).map((r) => r.verb).join(" and ")}`),
+                    "Nothing was changed."
+                ].join("\n"));
+            }
+            if (blocker) {
+                blocker.resolved = true;
+                blocker.answer = answer;
+                if (amended?.length)
+                    blocker.amendedComponents = amended;
+                plan.dirty = true;
+            }
+            const dropped = [];
+            const promoted = [];
+            for (const r of hits) {
+                if (r.verb === "drop") {
+                    removeEntry(plan, r.entry);
+                    dropped.push(entryLabel(r.entry));
+                }
+                else {
+                    // The return value says whether a flag was actually present; a promote of something
+                    // never marked provisional stays a no-op that reports success, exactly as before.
+                    clearProvisional(plan, r.entry);
+                    promoted.push(entryLabel(r.entry));
+                }
+            }
+            // A blockerless reconcile leaves its own attributable record — the plan must state WHY a
+            // provisional flag cleared, or the next reader is back to archaeology.
+            if (!blocker) {
+                const existing = Array.isArray(plan.document.reconciliations) ? plan.document.reconciliations : [];
+                plan.document.reconciliations = [
+                    ...existing,
+                    { reason, ...(promoted.length ? { promoted } : {}), ...(dropped.length ? { dropped } : {}), at: new Date().toISOString() }
+                ];
+                plan.dirty = true;
+            }
+            await fs.writeFile(file, serializePlanFile(plan), "utf8");
+            const open = blockers.filter((b) => !b.resolved).length;
+            return ok([
+                blocker ? `${extId} blocker ${blockerId} recorded as answered.` : `${extId} plan reconciled (no local blocker).`,
+                blocker ? `  answer: ${answer}` : `  reason: ${reason}`,
+                ...(amended?.length ? [`  amended: ${amended.join(", ")}`] : []),
+                ...(promoted.length ? [`  promoted (no longer provisional, now assemblable): ${promoted.join(", ")}`] : []),
+                ...(dropped.length ? [`  dropped from the plan (${before} -> ${componentCount()} components): ${dropped.join(", ")}`] : []),
+                open > 0
+                    ? `  ${open} blocker(s) still open on this requirement.`
+                    : "  no blockers remain open on this requirement.",
+                "",
+                "If this answer changed an authored file, edit it under requirements/" + extId + "/authored/ —",
+                "the wave tree is a build artifact that direct_lint/direct_apply rebuild from that file on every call."
+            ].join("\n"), {
+                extId,
+                ...(blocker ? { blockerId, answer } : { reason }),
+                openBlockers: open,
+                ...(amended?.length ? { amended } : {}),
+                ...(promoted.length ? { promoted } : {}),
+                ...(dropped.length ? { dropped } : {})
+            });
+        }
+        catch (error) {
+            if (error instanceof WorkspaceError)
+                return fail(error.code, error.message);
+            return internalError(error);
+        }
+    });
+}