@bendyline/gilde 0.1.39 → 0.1.41

package/data/craftbook-templates/re/refactor-module/versions/2.0.0/craftbook.json

@@ -0,0 +1,509 @@
+{
+  "id": "refactor-module",
+  "name": "Behavior-Preserving Refactor",
+  "description": "Restructure code with the discipline that makes refactoring safe, and with each claim mechanically verified. First BASELINE: run the suite and record it green before anything moves — and where the code about to be reshaped has no tests, write characterization tests FIRST, pinning CURRENT behavior bugs included, because a refactor without a behavioral pin is just hopeful editing. The baseline also records the structural measurements the refactor targets (duplicated blocks, function lengths, tangled responsibilities) with the method used to count them. Then PLAN: the target structure and a sequence of small stages, each individually reversible and each leaving the tree working. Then CHANGE: execute stage by stage at the real sites — never a prescribed scratch file — running the suite between stages so a red step is reverted or narrowed, not stacked on. Then VERIFY: re-measure with the SAME method, quote before and after side by side, and show the whole suite green. Finally an independent reviewer grades the chain against fixed criteria — behavior preserved, target genuinely moved, no stage left red — and a REVISE verdict routes the work back automatically with concrete findings. Needs a project whose tests run via `npm run test`. Works identically whether the run edits the project directly or drafts a change proposal for the user to apply.",
+  "plan": "Record a green baseline and the guardrail (characterization tests first when coverage is thin) -> plan small reversible stages -> restructure stage by stage with the suite green throughout -> re-measure with the same method and prove behavior held -> enforced independent review.",
+  "entryStepId": "baseline",
+  "triggers": [
+    "refactor this module",
+    "clean up the code",
+    "improve code structure",
+    "behavior-preserving refactor",
+    "reduce duplication"
+  ],
+  "commands": [
+    {
+      "scope": "script",
+      "name": "test",
+      "reason": "The suite is the guardrail: it must be green before any restructuring starts, stay green between stages, and be green at the end. The gates verify the green-before/green-after receipts from real runs, not the author's claims."
+    }
+  ],
+  "paramSchema": {
+    "type": "object",
+    "properties": {
+      "scope": {
+        "type": "string",
+        "title": "What to refactor",
+        "description": "The module, folder, duplication, or structural problem to work on. Leave empty when the task description already carries it.",
+        "default": ""
+      },
+      "workPath": {
+        "type": "string",
+        "title": "Working folder",
+        "description": "Per-task working folder in the artifacts drawer. Defaults to this task's own folder so runs never collide; override with a stable name when you deliberately want runs to share files.",
+        "default": "{{task.dir}}"
+      }
+    }
+  },
+  "steps": [
+    {
+      "id": "baseline",
+      "name": "Capture the baseline",
+      "description": "Record the current truth before changing anything: suite green, structural measurements, and the guardrail — with characterization tests added first where coverage is thin.",
+      "prompt": "The refactor scope: {{scope}}\n\nCapture the current truth before changing anything — measure BEFORE, so the improvement can be proven later with the same method. Read the involved source and find how this project runs its tests (`list_package_scripts`, then read the existing test layout). Run the suite with `run_package_script` (`test`) and confirm it is GREEN before any restructuring; if it is already red, stop and report that honestly instead of refactoring on a broken base. If the command needs first-use approval, say so and wait rather than guessing.\n\nWhere the code you are about to restructure lacks tests, write characterization tests FIRST: tests that pin the CURRENT behavior — bugs and quirks included — in the project's real test layout and style. They are the guardrail. Run them and record that they pass against today's code; do not fix anything they reveal.\n\nThen record the structural measurements this refactor targets, as numbers gathered by a stated method: duplicated blocks and where each copy lives, function lengths, file sizes, tangled responsibilities — counted, not adjectived.\n\nWrite `{{workPath}}/baseline.md` with exactly these sections: `## Current behavior` (what the code does today and which tests pin it, including any characterization tests you just added), `## Measurements` (the structural numbers and the exact method used to gather them), `## Guardrail` (what must not change: public API, observable behavior, and the suite staying green). Cite the real files involved with backtick paths.\n\nObservable handoff: write the completed result to `{{workPath}}/baseline.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.",
+      "suggestedRole": "software engineer",
+      "capabilityFloor": "medium",
+      "advanceWhen": {
+        "file": "{{workPath}}/baseline.md",
+        "minBytes": 500,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "artifact": true,
+        "goto": "plan"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/baseline.md",
+            "bytes": 500,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/baseline.md",
+            "sniff": "nonempty",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/baseline.md",
+            "pattern": "^##\\s+Current behavior",
+            "flags": "im",
+            "label": "Current behavior section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/baseline.md",
+            "pattern": "^##\\s+Measurements[\\s\\S]*\\d",
+            "flags": "im",
+            "label": "Measurements section with recorded numbers",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/baseline.md",
+            "pattern": "^##\\s+Guardrail",
+            "flags": "im",
+            "label": "Guardrail section",
+            "artifact": true
+          },
+          {
+            "kind": "citationsResolve",
+            "file": "{{workPath}}/baseline.md",
+            "minCitations": 2,
+            "artifact": true
+          },
+          {
+            "kind": "commandEvidence",
+            "script": "test",
+            "expect": "pass",
+            "label": "green before the work starts"
+          }
+        ],
+        "onReject": "baseline",
+        "maxAttempts": 4
+      },
+      "next": "plan"
+    },
+    {
+      "id": "plan",
+      "name": "Plan reversible stages",
+      "description": "Design the target structure and an ordered sequence of small stages, each individually reversible and each leaving the tree working. No source edits.",
+      "prompt": "Read `{{workPath}}/baseline.md`, then design the restructure as a sequence of small stages. State the target structure concretely: what exists after the refactor that does not exist now, and what disappears. Break the work into ordered stages where EACH stage is individually reversible and leaves the tree working with the suite green — extract this function, move that block behind a seam, collapse the duplicate — never a big-bang rewrite. Name the files each stage touches. State the acceptance criteria: the measured target from the baseline moving (with the figures it should reach), the suite green after every stage, and the public API unchanged unless you explicitly declare a break here and say why. Do not edit any source in this phase.\n\nWrite `{{workPath}}/plan.md` with exactly these sections: `## Target` (the end structure), `## Stages` (numbered, each reversible, each naming its files), `## Acceptance criteria`. Cite the real files with backtick paths. Before working, open `{{workPath}}/baseline.md` with `read_artifact`.\n\nObservable handoff: write the completed result to `{{workPath}}/plan.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.",
+      "suggestedRole": "software architect",
+      "capabilityFloor": "medium",
+      "consumes": [
+        {
+          "file": "{{workPath}}/baseline.md",
+          "artifact": true
+        }
+      ],
+      "advanceWhen": {
+        "file": "{{workPath}}/plan.md",
+        "minBytes": 500,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "artifact": true,
+        "goto": "change"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/plan.md",
+            "bytes": 500,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/plan.md",
+            "sniff": "nonempty",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/plan.md",
+            "pattern": "^##\\s+Target",
+            "flags": "im",
+            "label": "Target section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/plan.md",
+            "pattern": "^##\\s+Stages",
+            "flags": "im",
+            "label": "Stages section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/plan.md",
+            "pattern": "^##\\s+Acceptance criteria",
+            "flags": "im",
+            "label": "Acceptance criteria section",
+            "artifact": true
+          },
+          {
+            "kind": "citationsResolve",
+            "file": "{{workPath}}/plan.md",
+            "minCitations": 2,
+            "artifact": true
+          }
+        ],
+        "onReject": "plan",
+        "maxAttempts": 4
+      },
+      "next": "change"
+    },
+    {
+      "id": "change",
+      "name": "Restructure stage by stage",
+      "description": "Execute the planned stages at the real sites, keeping the suite green between stages.",
+      "prompt": "Read `{{workPath}}/plan.md` and `{{workPath}}/baseline.md`, then execute the stages in order at the REAL sites — edit the actual files with `read_file` plus `write_file`/`replace_in_file`; there is no prescribed output path for source changes and never a scratch copy. After EACH stage, run the suite with `run_package_script` (`test`) and confirm it is still green before starting the next; a stage that goes red gets reverted or narrowed until green, not stacked on. Keep behavior identical: no fixes or features smuggled in under cover of the restructure — if you find a genuine bug, record it in your notes for the user instead of silently changing behavior the tests pin. Keep the characterization tests from the baseline; they ride along as permanent guards.\n\nWrite `{{workPath}}/change-notes.md` with exactly these sections: `## Stages executed` (each stage, in order, with its suite-green confirmation), `## Files touched` (backtick path per line), `## Deviations from plan` (anything done differently than plan.md and why; write `none` honestly when there are none). Before working, open `{{workPath}}/baseline.md`, `{{workPath}}/plan.md` with `read_artifact`.\n\nObservable handoff: write the completed result to `{{workPath}}/change-notes.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.",
+      "suggestedRole": "software engineer",
+      "capabilityFloor": "medium",
+      "consumes": [
+        {
+          "file": "{{workPath}}/baseline.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/plan.md",
+          "artifact": true
+        }
+      ],
+      "advanceWhen": {
+        "file": "{{workPath}}/change-notes.md",
+        "minBytes": 600,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "artifact": true,
+        "goto": "verify"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/change-notes.md",
+            "bytes": 600,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/change-notes.md",
+            "sniff": "nonempty",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/change-notes.md",
+            "pattern": "^##\\s+Stages executed",
+            "flags": "im",
+            "label": "Stages executed section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/change-notes.md",
+            "pattern": "^##\\s+Files touched",
+            "flags": "im",
+            "label": "Files touched section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/change-notes.md",
+            "pattern": "^##\\s+Deviations from plan",
+            "flags": "im",
+            "label": "Deviations from plan section",
+            "artifact": true
+          },
+          {
+            "kind": "citationsResolve",
+            "file": "{{workPath}}/change-notes.md",
+            "minCitations": 2,
+            "artifact": true
+          }
+        ],
+        "onReject": "change",
+        "maxAttempts": 4
+      },
+      "next": "verify"
+    },
+    {
+      "id": "verify",
+      "name": "Re-measure and verify",
+      "description": "Re-measure with the same method as the baseline, quote both figures, and record the suite green.",
+      "prompt": "Prove the refactor with fresh eyes. Read `{{workPath}}/baseline.md` and re-measure the SAME structural numbers with the SAME method it records — the comparison is meaningless if the method moved. Quote the before figure from the baseline and the after figure side by side. Then run the whole suite with `run_package_script` (`test`) and record the green result. Check the guardrail: exports, signatures, and observable behavior unchanged unless plan.md declared a break. Anything you could not actually re-run gets labeled unverified, never claimed.\n\nWrite `{{workPath}}/verification.md` with exactly these sections: `## Before / after` (each baseline measurement quoted next to its re-measured value, same method), `## Suite` (the full-suite result from the real run), `## Result` (behavior preserved and target moved, or what remains unverified and why). Before working, open `{{workPath}}/baseline.md` with `read_artifact`.\n\nObservable handoff: write the completed result to `{{workPath}}/verification.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.",
+      "suggestedRole": "software engineer",
+      "capabilityFloor": "medium",
+      "consumes": [
+        {
+          "file": "{{workPath}}/baseline.md",
+          "artifact": true
+        }
+      ],
+      "advanceWhen": {
+        "file": "{{workPath}}/verification.md",
+        "minBytes": 400,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "artifact": true,
+        "goto": "evaluate"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/verification.md",
+            "bytes": 400,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/verification.md",
+            "sniff": "nonempty",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/verification.md",
+            "pattern": "^##\\s+Before\\s*/\\s*after[\\s\\S]*\\d",
+            "flags": "im",
+            "label": "Before / after section with both figures",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/verification.md",
+            "pattern": "^##\\s+Suite",
+            "flags": "im",
+            "label": "Suite section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/verification.md",
+            "pattern": "^##\\s+Result",
+            "flags": "im",
+            "label": "Result section",
+            "artifact": true
+          },
+          {
+            "kind": "commandEvidence",
+            "script": "test",
+            "expect": "pass",
+            "label": "green after the restructure (verified run receipt)"
+          }
+        ],
+        "onReject": "verify",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate the deliverable",
+      "description": "Independently grade the observable deliverable and route it to finish, repair, or user escalation.",
+      "prompt": "Review `{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone.\n\n1. baseline.md records a genuinely green suite from a real run receipt before any restructuring, and pins the guardrail — with characterization tests written first (pinning current behavior, bugs included) wherever the touched area lacked coverage.\n2. Observable behavior unchanged (or changed only as the plan declared): public API and outputs held, and the pinning tests still pass unmodified — open the touched files and the tests; do not grade from change-notes.md alone.\n3. The measured target moved against the recorded baseline using the same method: verification.md quotes both figures side by side, and the duplication/structure improvement is visible in the real files, not just claimed.\n4. No stage left the suite red (receipts, not claims): the recorded runs show green between stages and green at the end.\n5. Every stage in change-notes.md matches a plan.md stage or an honestly recorded deviation, and every touched file it names exists.\n6. The public API is unchanged unless plan.md explicitly declared a break, and no fix or feature was smuggled in under cover of the restructure.\n\nOpen `{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md` with `read_artifact`. Write the evidence-backed review to `{{workPath}}/review.md` in the artifacts drawer with `write_artifact`.\n\nList the findings as a markdown table with columns `| Severity | File | Line | Problem | Fix |` (severities: critical/major/minor/nit; empty table only on PASS). Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. The gate ENFORCES the verdict: a well-formed REVISE is rejected and routed back to `repair` automatically, carrying your findings — so list every finding in the table with a concrete fix. On PASS, `advance_task_step` to `finish`. Never write PASS while a criterion is unmet.",
+      "suggestedRole": "refactoring reviewer",
+      "consumes": [
+        {
+          "file": "{{workPath}}/verification.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/baseline.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/plan.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/change-notes.md",
+          "artifact": true
+        }
+      ],
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/review.md",
+            "bytes": 400,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/review.md",
+            "pattern": "Verdict:\\s*(?:PASS|REVISE)",
+            "flags": "i",
+            "label": "explicit PASS or REVISE verdict",
+            "artifact": true
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkFixReview",
+            "scope": "standard",
+            "inputs": {
+              "reviewPath": "{{workPath}}/review.md",
+              "fixStepId": "repair"
+            }
+          }
+        ],
+        "onReject": "evaluate",
+        "maxAttempts": 4
+      },
+      "next": "finish"
+    },
+    {
+      "id": "repair",
+      "name": "Repair the deliverable",
+      "description": "Fix only the concrete gaps from the latest independent review.",
+      "prompt": "Read `{{workPath}}/review.md` with `read_artifact` and repair every failed criterion in `{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `{{workPath}}/verification.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.",
+      "suggestedRole": "software engineer",
+      "consumes": [
+        {
+          "file": "{{workPath}}/review.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/verification.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/baseline.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/plan.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/change-notes.md",
+          "artifact": true
+        }
+      ],
+      "advanceWhen": {
+        "file": "{{workPath}}/verification.md",
+        "minBytes": 400,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "artifact": true,
+        "goto": "evaluate"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/verification.md",
+            "bytes": 400,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/verification.md",
+            "sniff": "nonempty",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/verification.md",
+            "pattern": "^##\\s+Before\\s*/\\s*after[\\s\\S]*\\d",
+            "flags": "im",
+            "label": "Before / after section with both figures",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/verification.md",
+            "pattern": "^##\\s+Suite",
+            "flags": "im",
+            "label": "Suite section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/verification.md",
+            "pattern": "^##\\s+Result",
+            "flags": "im",
+            "label": "Result section",
+            "artifact": true
+          },
+          {
+            "kind": "commandEvidence",
+            "script": "test",
+            "expect": "pass",
+            "label": "green after the restructure (verified run receipt)"
+          }
+        ],
+        "onReject": "repair",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All deterministic and reviewer criteria passed.",
+      "prompt": "The independent review passed. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`{{workPath}}/verification.md`, `{{workPath}}/baseline.md`, `{{workPath}}/plan.md`, `{{workPath}}/change-notes.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.",
+      "suggestedRole": "project lead",
+      "consumes": [
+        {
+          "file": "{{workPath}}/review.md",
+          "artifact": true
+        }
+      ],
+      "terminal": true
+    },
+    {
+      "id": "needs-user",
+      "name": "Escalate unresolved concerns",
+      "description": "The bounded repair loop ended without a defensible pass.",
+      "prompt": "The deliverable did not pass after 3 review rounds. Do not claim success. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.",
+      "suggestedRole": "project lead",
+      "consumes": [
+        {
+          "file": "{{workPath}}/review.md",
+          "artifact": true
+        }
+      ],
+      "terminal": true
+    }
+  ],
+  "diffpackCapable": true,
+  "capabilityFloor": "medium",
+  "version": "2.0.0",
+  "releasedAt": "2026-08-24T00:00:00.000Z",
+  "minGezelVersion": "1.26236"
+}