@tendrilapp/cli 0.1.29 → 0.1.31

package/dist/SKILL.md

@@ -131,7 +131,12 @@ Batch runs (several components in one session):
 2. `tendril_record_plan` with the response text passed VERBATIM via
    `metadataParts` (one array entry per response block, in order —
    single-block responses may use `metadata` instead; nothing is saved
-   to a file, and never hand-join blocks) → the queue plan. The plan
+   to a file, and never hand-join blocks), AND `figmaFile` set to the
+   file key from the URL you were handed (figma.com/design/<KEY>/… —
+   pass exactly KEY): it is recorded as the set's file identity for
+   cross-bundle composition, captured at plan time only and never
+   backfillable — a set planned without it can never join across
+   bundles → the queue plan. The plan
    records the FULL variant matrix — every pose the set defines
    (sampling exists only as a human-run CLI flag; the MCP surface
    cannot sample). CROSS-CHECK `variantsFound` in the plan output
@@ -254,8 +259,13 @@ Batch runs (several components in one session):
    CSS. Import every React API you use.
 3. `tendril_engine_score` → read the per-config results and feedback.
    Fix FAIL configs without regressing PASS configs; re-score.
-4. Stop when `allPass` is true, or after two consecutive rounds with
-   no improvement — then report the honest final state.
+4. Stop when `allPass` is true. Two consecutive rounds with no
+   improvement is a TRIGGER TO INSPECT, not to stop: open the
+   verify-evidence diff images for the worst configs and look before
+   deciding (a measured run scored byte-identical twice, inspected
+   the diffs, and round 3 went 27/27 certified — a stop rule would
+   have shipped 5/27). Stop only after an inspection round produced
+   no fix hypothesis — then report the honest final state.
 5. MODEL SELECTION — mechanical AND asked. `engine brief` and
    `engine score` refuse to run without a declared model, so the
    choice must be settled first. When a user is present, ask before

package/dist/tendril-mcp.js

@@ -37,7 +37,8 @@ var TOOLS = [
       metadata: optStr("ONLY when get_metadata genuinely returned one single block: its text verbatim (otherwise use metadataParts)"),
       metadataFiles: z.array(z.string()).optional().describe('saved verbatim get_metadata envelope file paths \u2014 JSON shape {"content":[{"type":"text","text":"<frame \u2026>"}]}; optionally <file>@<frameId>. Prefer metadataParts: no file to write'),
       defaults: z.array(z.string()).optional().describe(`axis defaults as "Axis=Value" (from the user's defaultsToConfirm answers; may re-plan a set with nothing recorded yet)`),
-      componentSet: optStr("record only this component set (the user's pick from a multiple-component-sets error)")
+      componentSet: optStr("record only this component set (the user's pick from a multiple-component-sets error)"),
+      figmaFile: optStr("the Figma file key from the design URL you were handed \u2014 figma.com/design/<KEY>/\u2026, pass exactly <KEY>. ALWAYS pass it on a fresh plan: it is the set's recorded file identity for cross-bundle composition (ADR-013), captured at plan time only and never backfillable later")
     }),
     // Texts ride temp files, never argv: Windows caps a command line at
     // ~32 KB and metadata envelopes can exceed it.
@@ -60,7 +61,11 @@ var TOOLS = [
         }
       }
       if (argvOut.length === 6) throw new Error("nothing to plan from \u2014 pass metadataParts (normal), metadata (single-block), or metadataFiles");
-      argvOut.push(...i["defaults"] !== void 0 ? ["--default", ...i["defaults"]] : [], ...i["componentSet"] !== void 0 ? ["--component-set", i["componentSet"]] : []);
+      argvOut.push(
+        ...i["defaults"] !== void 0 ? ["--default", ...i["defaults"]] : [],
+        ...i["componentSet"] !== void 0 ? ["--component-set", i["componentSet"]] : [],
+        ...typeof i["figmaFile"] === "string" ? ["--figma-file", i["figmaFile"]] : []
+      );
       return argvOut;
     }
   },

package/dist/tendril.js

@@ -1069,6 +1069,9 @@ function planSet(setDir, component, symbols, opts = {}) {
   const manifest = {
     version: 1,
     component,
+    ...opts.figmaFile !== void 0 ? { figmaFile: opts.figmaFile } : {},
+    ...opts.componentSetNode !== void 0 ? { componentSetNode: opts.componentSetNode } : {},
+    ...opts.figmaComponentName !== void 0 ? { figmaComponentName: opts.figmaComponentName } : {},
     ...opts.sourceFrames !== void 0 ? { sourceFrames: opts.sourceFrames } : {},
     ...opts.variantScope !== void 0 ? { variantScope: opts.variantScope } : {},
     ...opts.defaults !== void 0 && Object.keys(opts.defaults).length > 0 ? { defaults: opts.defaults } : {},
@@ -1215,8 +1218,27 @@ var init_session = __esm({
     SessionManifestSchema = z4.object({
       version: z4.literal(1),
       component: z4.string().min(1),
+      /** ADR-013 slice 1 (v4, capture-only): cross-set identity, captured
+       * at RECORD TIME on fresh plans only — NEVER backfilled (the
+       * recording-set hash covers this file's bytes, so adding fields to
+       * a set that already produced bundles voids their provenance).
+       * `figmaFile` is the Figma file key from the URL the agent host was
+       * handed — an AGENT ASSERTION, disclosed, never enforcement-bearing
+       * alone (ADR-013 §1). `componentSetNode`/`figmaComponentName` are
+       * the enclosing set's id and Figma-side name as the planner's own
+       * metadata parse saw them — the identity that stops a re-recording
+       * of the same component from reading as a different one (`component`
+       * below is the plan-time DISPLAY name; the measured case recorded
+       * one control as "Lucent Control (Dark)" and "control"). All
+       * optional: legacy sets simply cannot join, disclosed. */
+      figmaFile: z4.string().regex(/^[A-Za-z0-9]{8,64}$/).optional(),
+      componentSetNode: z4.string().optional(),
+      figmaComponentName: z4.string().optional(),
       sourceFrames: z4.record(z4.string(), z4.string()).optional(),
-      reps: z4.array(z4.object({ slug: z4.string(), nodeId: z4.string(), sourceFrame: z4.string().optional() })).min(1),
+      /** Per-rep `componentKey` is SEEDED (ADR-013 v4: the one-call MCP
+       * probe decides whether anything can ever fill it) so interim sets
+       * are not born cross-file-dead if keys turn out to be available. */
+      reps: z4.array(z4.object({ slug: z4.string(), nodeId: z4.string(), sourceFrame: z4.string().optional(), componentKey: z4.string().optional() })).min(1),
       notRecorded: z4.string().optional(),
       /** Explicit axis-default overrides from `record plan --default`.
        * Recorded-truth-side on purpose: the default decides which pose an
@@ -2232,6 +2254,8 @@ async function runTokenLint(css, fileLabel = "generated.css", definedVars2, reco
         property: "custom-property-ident",
         message: `var(${name}) is not a legal custom property reference \u2014 the browser drops the whole declaration`
       });
+    } else if (name.startsWith("--tendril-")) {
+      continue;
     } else if (definedVars2 !== void 0 && !definedVars2.has(name) && !ownDefs.has(name)) {
       violations.push({
         file: fileLabel,
@@ -7871,10 +7895,10 @@ function symbolsFromMetadataEnvelope(file, sourceFrame) {
         nodeId: node.id,
         name: node.name,
         ...sourceFrame !== void 0 ? { sourceFrame } : {},
-        ...ancestor !== void 0 ? { setName: ancestor } : {}
+        ...ancestor !== void 0 ? { setName: ancestor.name, setNodeId: ancestor.id } : {}
       });
     }
-    const next = node.type !== "COMPONENT" && node.name !== "" ? node.name : ancestor;
+    const next = node.type !== "COMPONENT" && node.name !== "" ? { name: node.name, id: node.id } : ancestor;
     for (const child of node.children) walk2(child, next);
   };
   const forest = parseMetadataForest(text);
@@ -8012,10 +8036,25 @@ function runRecordPlan(opts) {
   if (metadataTruncated) {
     warn(opts, "get_metadata response appears TRUNCATED (unclosed structure) \u2014 the variant list below may be incomplete. Cross-check variantsFound against the variant count Figma shows for this component set; re-fetch the metadata if lower.");
   }
+  if (opts.figmaFile !== void 0 && !/^[A-Za-z0-9]{8,64}$/.test(opts.figmaFile)) {
+    fail(opts, ExitCode.InputValidation, {
+      error: `--figma-file must be the bare file key from the Figma URL (letters and digits only) \u2014 got ${JSON.stringify(opts.figmaFile)}`,
+      code: "bad-figma-file",
+      remediation: "From https://www.figma.com/design/<KEY>/<name>?node-id=\u2026, pass exactly <KEY>."
+    });
+  }
+  const setIdentity = (() => {
+    if (variantScope !== "component-set") return {};
+    const ids = [...new Set(symbols.map((s) => s.setNodeId).filter((x) => x !== void 0))];
+    const names = [...new Set(symbols.map((s) => s.setName).filter((x) => x !== void 0))];
+    return ids.length === 1 && names.length === 1 ? { componentSetNode: ids[0], figmaComponentName: names[0] } : {};
+  })();
   const { manifest, plan, resumed, toppedUp } = planSet(opts.setDir, opts.component, symbols, {
     ...Object.keys(defaults).length > 0 ? { defaults } : {},
     ...opts.sample === true ? { sample: true } : {},
-    variantScope
+    variantScope,
+    ...opts.figmaFile !== void 0 ? { figmaFile: opts.figmaFile } : {},
+    ...setIdentity
   });
   const defaultReports = reportAxisDefaults(symbols, Object.keys(defaults).length > 0 ? defaults : void 0);
   const toConfirm = resumed ? [] : defaultReports.filter((r) => (r.rule === "non-interaction" || r.rule === "frequency") && r.domain.length > 1);
@@ -11146,14 +11185,15 @@ function latticeCoverage(setManifest, scoredConfigs) {
   const lattice = setManifest.latticeNames?.length;
   const established = setManifest.variantScope === "component-set";
   const notRecorded = setManifest.notRecorded !== void 0 && setManifest.notRecorded !== "" ? { notRecorded: setManifest.notRecorded } : {};
-  if (lattice === void 0) return { latticeConfigs: null, ...notRecorded };
+  const latticeUnestablished = setManifest.variantScope === "selection" ? "the recording was planned from a node SELECTION, not from a component set \u2014 the plan counted the nodes it was handed and could not see whether the set holds more variants, so the number of unrecorded poses is UNKNOWN, not zero" : setManifest.variantScope === "component-set" ? "the planner saw the component set and it declares no variant axes \u2014 the planned pose(s) are the whole set as Figma showed it, but there is no variant lattice to count" : "this set was planned before variant scope was recorded, so whether its lattice came from a component set or from a handed-in selection was never established \u2014 the number of unrecorded poses is unknown, not zero";
+  if (lattice === void 0) return { latticeConfigs: null, latticeUnestablished, ...notRecorded };
   if (established) return { latticeConfigs: lattice, unrecordedConfigs: Math.max(0, lattice - scoredConfigs), ...notRecorded };
   return {
     latticeConfigs: null,
     // The count is still worth reporting — it is just not a
     // denominator, and the name has to stop implying that it is.
     variantsPlanned: lattice,
-    latticeUnestablished: setManifest.variantScope === "selection" ? "the recording was planned from a node SELECTION, not from a component set \u2014 the plan counted the nodes it was handed and could not see whether the set holds more variants, so the number of unrecorded poses is UNKNOWN, not zero" : "this set was planned before variant scope was recorded, so whether its lattice came from a component set or from a handed-in selection was never established \u2014 the number of unrecorded poses is unknown, not zero",
+    latticeUnestablished,
     ...notRecorded
   };
 }
@@ -11557,8 +11597,10 @@ ${certified}/${statuses.length} certified \xB7 ${report.coverage.pass}/${statuse
         process.stdout.write(`LATTICE   all ${cov.latticeConfigs} poses of the component set's own lattice are recorded and scored \u2014 the denominator is the set's, not the recorded subset's
 `);
       } else if (cov.latticeConfigs === null) {
-        process.stdout.write(`COVERAGE  denominator unknown (set predates lattice tracking) \u2014 scored configs are verified; completeness is not established
-`);
+        process.stdout.write(
+          `COVERAGE  denominator unknown \u2014 ${cov.latticeUnestablished ?? "set predates lattice tracking"} \u2014 scored configs are verified; completeness is not established
+`
+        );
       }
     }
     process.stdout.write(`environment: chrome=${report.environment.chromeVersion ?? report.environment.chrome} fonts=${report.environment.fontsManifestSha256 ?? "UNRESOLVED"}
@@ -11767,7 +11809,7 @@ ${segments}`;
         `Run \`${tendrilCommand(
           `engine score ${quoteArg(ref)} ${quoteArg(candidateDirSuggestion)} --bar ${opts.bar} --model ${opts.model ?? "<declared-model>"} --json`
         )}\` \u2014 the CLI is the sole judge, and it refuses to score an undeclared model. If you wrote the bundle elsewhere, pass that directory instead.`,
-        "Apply the returned feedback and re-score. Stop when all checks pass or two consecutive scores fail to improve.",
+        "Apply the returned feedback and re-score. Stop when all checks pass. Two consecutive non-improving scores mean INSPECT the verify-evidence diffs before deciding \u2014 stop only when inspection yields no fix hypothesis (a measured run was byte-identical twice, then went 27/27 after reading the diffs).",
         "Never edit recording sets; never claim scores yourself \u2014 only the score command's output counts."
       ]
     },
@@ -12225,7 +12267,8 @@ var init_server = __esm({
           metadata: optStr("ONLY when get_metadata genuinely returned one single block: its text verbatim (otherwise use metadataParts)"),
           metadataFiles: z12.array(z12.string()).optional().describe('saved verbatim get_metadata envelope file paths \u2014 JSON shape {"content":[{"type":"text","text":"<frame \u2026>"}]}; optionally <file>@<frameId>. Prefer metadataParts: no file to write'),
           defaults: z12.array(z12.string()).optional().describe(`axis defaults as "Axis=Value" (from the user's defaultsToConfirm answers; may re-plan a set with nothing recorded yet)`),
-          componentSet: optStr("record only this component set (the user's pick from a multiple-component-sets error)")
+          componentSet: optStr("record only this component set (the user's pick from a multiple-component-sets error)"),
+          figmaFile: optStr("the Figma file key from the design URL you were handed \u2014 figma.com/design/<KEY>/\u2026, pass exactly <KEY>. ALWAYS pass it on a fresh plan: it is the set's recorded file identity for cross-bundle composition (ADR-013), captured at plan time only and never backfillable later")
         }),
         // Texts ride temp files, never argv: Windows caps a command line at
         // ~32 KB and metadata envelopes can exceed it.
@@ -12248,7 +12291,11 @@ var init_server = __esm({
             }
           }
           if (argvOut.length === 6) throw new Error("nothing to plan from \u2014 pass metadataParts (normal), metadata (single-block), or metadataFiles");
-          argvOut.push(...i["defaults"] !== void 0 ? ["--default", ...i["defaults"]] : [], ...i["componentSet"] !== void 0 ? ["--component-set", i["componentSet"]] : []);
+          argvOut.push(
+            ...i["defaults"] !== void 0 ? ["--default", ...i["defaults"]] : [],
+            ...i["componentSet"] !== void 0 ? ["--component-set", i["componentSet"]] : [],
+            ...typeof i["figmaFile"] === "string" ? ["--figma-file", i["figmaFile"]] : []
+          );
           return argvOut;
         }
       },
@@ -14068,7 +14115,7 @@ function buildProgram() {
     await runActivate2({ ...flags, serviceUrl: local["serviceUrl"] });
   });
   const record = program.command("record").description("Agent-driven recording protocol: plan the queue, get instructions, ingest verbatim envelopes, resume from disk.");
-  record.command("plan").requiredOption("--set <dir>", "recording set directory").requiredOption("--component <name>", "component/system name").option("--metadata <file...>", "verbatim get_metadata envelope(s), optionally <file>@<frameId>").option("--metadata-raw-file <file>", "the get_metadata response TEXT exactly as received (single block); the CLI builds the envelope itself").option("--metadata-raw-parts-file <file>", "a JSON array of the get_metadata response blocks, each verbatim, in order (multi-block responses)").option("--default <axis=value...>", "explicit axis default, e.g. --default State=Rest (repeatable; persisted to the manifest; may re-plan an unrecorded set)").option("--component-set <name>", "when the metadata holds several component sets, record only this one (name = the set label in the plan error)").option("--sample", "cost sampling: anchor + one-factor + conflict crosses only (the FULL variant matrix is the default; sampling is blind to multi-axis interactions)").action(async (_o, cmd) => {
+  record.command("plan").requiredOption("--set <dir>", "recording set directory").requiredOption("--component <name>", "component/system name").option("--metadata <file...>", "verbatim get_metadata envelope(s), optionally <file>@<frameId>").option("--metadata-raw-file <file>", "the get_metadata response TEXT exactly as received (single block); the CLI builds the envelope itself").option("--metadata-raw-parts-file <file>", "a JSON array of the get_metadata response blocks, each verbatim, in order (multi-block responses)").option("--default <axis=value...>", "explicit axis default, e.g. --default State=Rest (repeatable; persisted to the manifest; may re-plan an unrecorded set)").option("--component-set <name>", "when the metadata holds several component sets, record only this one (name = the set label in the plan error)").option("--sample", "cost sampling: anchor + one-factor + conflict crosses only (the FULL variant matrix is the default; sampling is blind to multi-axis interactions)").option("--figma-file <key>", "the Figma file key from the design URL (figma.com/design/<KEY>/\u2026) \u2014 recorded as the set's file identity for cross-bundle composition (ADR-013; fresh plans only, never backfilled)").action(async (_o, cmd) => {
     const flags = globalFlags(cmd.parent.parent);
     const local = cmd.opts();
     const { runRecordPlan: runRecordPlan2 } = await Promise.resolve().then(() => (init_record(), record_exports));
@@ -14077,6 +14124,7 @@ function buildProgram() {
       setDir: local["set"],
       component: local["component"],
       sample: local["sample"],
+      ...local["figmaFile"] !== void 0 ? { figmaFile: local["figmaFile"] } : {},
       ...local["metadata"] !== void 0 ? { metadataFiles: local["metadata"] } : {},
       ...local["metadataRawFile"] !== void 0 ? { metadataRawFile: local["metadataRawFile"] } : {},
       ...local["metadataRawPartsFile"] !== void 0 ? { metadataRawPartsFile: local["metadataRawPartsFile"] } : {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tendrilapp/cli",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Figma design systems → verified React components. CLI ruler + MCP server.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",