canicode 0.10.2 → 0.10.4

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "canicode",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "mcpName": "io.github.let-sunny/canicode",
-  "description": "Score your Figma designs with AI-calibrated rules. CLI + MCP server.",
+  "description": "Lint Figma designs for AI code-gen and roundtrip the answers back into the file. CLI + MCP server.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -27,6 +27,7 @@
     "lint": "tsc --noEmit",
     "build:plugin": "bash scripts/build-plugin.sh",
     "sync-docs": "tsx scripts/sync-rule-docs.ts",
+    "check:skill-determinism": "tsx scripts/check-skill-determinism.ts",
     "clean": "rm -rf dist skills"
   },
   "files": [

package/skills/canicode-gotchas/SKILL.md

@@ -9,7 +9,7 @@ Run a gotcha survey on a Figma design to identify implementation pitfalls, colle
 
 ## Prerequisites
 
-- **canicode MCP server** (preferred): `claude mcp add canicode -e FIGMA_TOKEN=figd_xxx -- npx -y -p canicode canicode-mcp`
+- **canicode MCP server** (preferred): `claude mcp add canicode -- npx --yes --package=canicode canicode-mcp` — long-form flags only; the short-form `-y -p` collides with `claude mcp add`'s parser (#366). The MCP server reads `FIGMA_TOKEN` from `~/.canicode/config.json` or the host environment, so do **not** pass `-e FIGMA_TOKEN=…` here (#364).
 - **Without canicode MCP** (fallback): the `canicode gotcha-survey --json` CLI produces the same response shape — no MCP installation required.
 - **FIGMA_TOKEN** configured for live Figma URLs
 
@@ -43,21 +43,50 @@ If `isReadyForCodeGen` is `true` or `questions` is empty:
 
 ### Step 3: Present questions to the user
 
-For each question in the `questions` array, present it to the user one at a time:
+The survey response carries a pre-computed `groupedQuestions.groups[].batches[]` shape so the SKILL never has to sort, partition, or maintain a batchable-rule whitelist in prose. The sort key, `_no-source` sentinel, and batchable-rule list all live in `core/gotcha/group-and-batch-questions.ts` with vitest coverage (per ADR-016). Iterate over it:
 
-```
-**[{severity}] {ruleId}** — node: {nodeName}
+For every `batch` in `groupedQuestions.groups.flatMap((g) => g.batches)`:
 
-{question}
+- **Single-question batch (`batch.questions.length === 1`)** — render the standard prompt for `batch.questions[0]`:
 
-> Hint: {hint}
-> Example: {example}
-```
+  ```
+  **[{severity}] {ruleId}** — node: {nodeName}
+
+  {question}
+
+  > Hint: {hint}
+  > Example: {example}
+  ```
+
+- **Batch of N ≥ 2 with `batch.batchable === true`** (#369) — render one shared prompt covering every member:
+
+  ```
+  **[{severity}] {ruleId}** — {batch.questions.length} instances:
+    - {nodeName₁}
+    - {nodeName₂}
+    - …
+
+  {sharedQuestionPrompt}
+
+  Reply with one answer to apply to all {batch.questions.length}, or **split** to answer each individually.
+
+  > Hint: {hint}
+  > Example: {example}
+  ```
+
+  Where `sharedQuestionPrompt` reuses the rule's `question` text with the per-node noun replaced by the rule's plural noun (e.g. "These layers all use FILL sizing without min/max constraints. What size boundaries should they share?" instead of repeating the singular phrasing N times).
 
-Wait for the user's answer before moving to the next question. The user may:
-- Answer the question directly
-- Say "skip" to skip a question
-- Say "n/a" if the question is not applicable
+- **Any batch with `batch.batchable === false`** is always rendered as a single-question prompt — the helper guarantees `questions.length === 1` for those (identity-typed answers like `non-semantic-name`, structural-mod rules).
+
+Wait for the user's answer before moving to the next batch. The user may:
+- Answer the question / batch directly
+- Say **split** (batch only) to fall back to per-question prompting for that batch
+- Say **skip** to skip the question / the entire batch
+- Say **n/a** if the question / the entire batch is not applicable
+
+When applying the batched answer, expand back to per-question records in Step 4 — the gotcha section format stores one record per `nodeId`.
+
+> The `groupedQuestions.groups[].instanceContext` field exists for the `canicode-roundtrip` SKILL's "Instance note" hoist (#370). This skill ignores it — every record gets its own `Instance context` bullet in Step 4 anyway.
 
 ### Step 4: Upsert the gotcha section
 
@@ -69,26 +98,35 @@ After collecting all answers, **upsert** this design's section into the `# Colle
 
 This file goes in the **user's project** (current working directory), NOT in the canicode repo. The Workflow region above **must never be modified** — only the `# Collected Gotchas` region below is touched.
 
-#### Step 4a: Compute `designKey`
+#### Step 4a: Use the `designKey` from the survey response
+
+`designKey` uniquely identifies the design so re-running on the same URL replaces the existing section in place. The survey response carries it on `survey.designKey` — read it directly. Do **not** parse the input URL in prose.
+
+The `core/contracts/design-key.ts` helper (`computeDesignKey`) handles every shape with vitest coverage so the SKILL stays ADR-016-compliant:
 
-`designKey` uniquely identifies the design so re-running on the same URL replaces the existing section in place. Parse it from the survey input:
+- **Figma URL** → `<fileKey>#<nodeId>` with `-` → `:` normalization on the nodeId. Example: `https://figma.com/design/abc123XYZ/My-File?node-id=42-100&t=ref` → `designKey = "abc123XYZ#42:100"`. Trailing query parameters (`?t=...`, `?mode=...`) are dropped.
+- **Figma URL without `node-id`** → just `<fileKey>` (file-level key).
+- **Fixture path / JSON file** → absolute path.
 
-- **Figma URL** — extract `fileKey` and `nodeId` from the URL and join them as `<fileKey>#<nodeId>`. Example: `https://figma.com/design/abc123XYZ/My-File?node-id=42-100` → `designKey = "abc123XYZ#42:100"` (convert `-` to `:` in nodeId, the same normalization the Figma MCP uses). Drop any other query-string parameters — only `node-id` matters for the key.
-- **Fixture path** — use the absolute path, e.g. `/Users/me/project/fixtures/simple.json`.
+#### Step 4b: Upsert via the canicode CLI
 
-Do **not** use the raw survey input URL as the key: trailing query parameters (`?t=...`, `?mode=...`) break string matching on re-runs.
+File-state detection (4-way: missing / valid / missing-heading / clobbered) and section walking (find existing `## #NNN — ...` by `Design key` substring, otherwise compute the next monotonic zero-padded NNN) are deterministic markdown operations and live in `core/gotcha/upsert-gotcha-section.ts` with vitest coverage — the SKILL never re-implements them in prose (per ADR-016).
+
+Render the per-design section markdown using the **Output Template** below with the literal string `{{SECTION_NUMBER}}` in the header (the CLI substitutes the right NNN for you — preserves it on replace, computes the next monotonic value on append). Then invoke:
+
+```bash
+npx canicode upsert-gotcha-section \
+  --file .claude/skills/canicode-gotchas/SKILL.md \
+  --design-key "<designKey from Step 4a>" \
+  --section -   # then pipe the rendered section markdown through stdin
+```
 
-#### Step 4b: Read the existing file and locate the target section
+The CLI prints a JSON result `{ state, action, sectionNumber, wrote, userMessage }`:
 
-1. Read `.claude/skills/canicode-gotchas/SKILL.md` if it exists.
-2. Detect the file's state using the two structural markers that uniquely identify each case — the YAML frontmatter (present on every `canicode init` install) and the `# Collected Gotchas` heading (present on every post-#340 install):
-   - **File missing** → tell the user to run `canicode init` first, then re-invoke this skill. Stop here.
-   - **File has YAML frontmatter AND a `# Collected Gotchas` heading** (the default shipped shape since #340) → proceed to step 3 below.
-   - **File has YAML frontmatter but no `# Collected Gotchas` heading** (an older workflow install, or a user-edited workflow that dropped the trailing heading) → preserve everything above unchanged and append a new `# Collected Gotchas` heading at the bottom, then proceed to step 3.
-   - **File missing the YAML frontmatter** (a pre-#340 single-design clobber — the old overwrite rewrote the frontmatter's `description` to the per-design variant, so a well-formed canicode frontmatter is the cleanest discriminator) → **do not attempt to reconstruct the workflow inline**. Tell the user: "Your gotchas SKILL.md looks like the pre-#340 single-design format. Run `canicode init --force` to restore the workflow, then re-run this survey — your answers will land in a clean numbered section." Stop here.
-3. Walk the existing `## #NNN — ...` sections under `# Collected Gotchas` and look for one whose `- **Design key**:` bullet matches the `designKey` from Step 4a. Substring match against the bullet value is sufficient.
-   - **Found** → replace that section in place. **Preserve its `#NNN` number** so external references (downstream skills, user notes) remain stable.
-   - **Not found** → append a new section at the bottom of the region. `#NNN = (highest existing number) + 1`, zero-padded to three digits. Never reuse a number that appeared earlier and was deleted; numbering is monotonic.
+- `wrote: true` → success. `action` is `"replace"` (preserved `sectionNumber`) or `"append"` (next monotonic `sectionNumber`).
+- `wrote: false` with `state: "missing"` → tell the user: *"Your gotchas SKILL.md is not installed yet. Run `canicode init` first, then re-invoke this skill."* Stop here.
+- `wrote: false` with `state: "clobbered"` → tell the user: *"Your gotchas SKILL.md is missing the canicode YAML frontmatter (pre-#340 single-design clobber). Run `canicode init --force` to restore the workflow, then re-run this survey — your answers will land in a clean numbered section."* Stop here.
+- `wrote: true` with `state: "missing-heading"` → silent recovery. The CLI injected the `# Collected Gotchas` heading and appended the section; the workflow region above is untouched.
 
 The Workflow region above must never be touched. Do NOT copy Workflow prose into the per-design section; the section only carries metadata + gotcha answers.
 
@@ -125,7 +163,7 @@ Each per-design section in the `# Collected Gotchas` region has this exact shape
 | `designName` | Figma file name or fixture name from the input |
 | `YYYY-MM-DD` | Today's date (the day you are running the survey) |
 | `figmaUrl` | The input URL or fixture path provided by the user |
-| `designKey` | `<fileKey>#<nodeId>` for Figma URLs, absolute path for fixtures (see Step 4a) |
+| `designKey` | `survey.designKey` from the gotcha-survey response (see Step 4a) |
 | `designGrade` | `designGrade` from gotcha-survey response |
 | `analyzedAt` | Current timestamp (ISO 8601) |
 | `ruleId` | `ruleId` from each question |