@bendyline/gilde 0.1.39 → 0.1.41

package/data/craftbook-templates/ac/accessibility-retrofit/versions/2.0.0/craftbook.json

@@ -0,0 +1,451 @@
+{
+  "id": "accessibility-retrofit",
+  "name": "Accessibility Retrofit",
+  "description": "Retrofit real pages to be genuinely accessible, with the discipline that separates repair from theater. First AUDIT: exercise the pages and markup the project actually serves and inventory concrete violations by class — missing or empty alt text on meaningful images, placeholder text doing a label's job, heading levels that jump, div-as-button controls a keyboard cannot reach, missing landmark structure, and contrast problems where the colors are derivable from the code — each violation recorded with its file, the concrete issue, and a priority. Then FIX every violation at its real site in the markup, styles, or components, preferring semantic elements over ARIA bolt-ons, real labels paired by for/id over placeholders, and specific purposeful alt text — with alt=\"\" reserved for genuinely decorative images and stated as such. Then VALIDATE by re-inspecting every fixed item and walking the keyboard path where runnable, saying plainly what was inspected versus actually exercised. Finally an independent reviewer grades the whole chain against fixed criteria — every label's for resolving to a real input id, monotonic heading order, no aria-label sprayed where a semantic element was the fix — and a REVISE verdict routes the work back automatically with concrete findings. This book also carries the full alt-text pass: classifying content versus decorative images and writing purposeful descriptions is part of the audit and fix, not a separate chore. Works identically whether the run edits the project directly or drafts a change proposal for the user to apply.",
+  "plan": "Audit the real pages and inventory violations by class -> fix each violation at its real site with semantic markup -> validate every item with an honest keyboard walk -> enforced independent review.",
+  "entryStepId": "audit",
+  "triggers": [
+    "accessibility fix",
+    "make it accessible",
+    "wcag compliance",
+    "a11y retrofit",
+    "fix accessibility",
+    "screen reader friendly",
+    "add alt text",
+    "generate alt text for images",
+    "make images accessible",
+    "alt text for my site",
+    "wcag image descriptions"
+  ],
+  "paramSchema": {
+    "type": "object",
+    "properties": {
+      "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": "audit",
+      "name": "Audit the real pages",
+      "description": "Exercise the pages the project actually serves and inventory concrete violations, each with its file, issue, and priority.",
+      "prompt": "Audit the REAL pages before anything is repaired. Find the markup this project actually serves — HTML files, templates, components — and read every involved file with `read_file`. Inventory concrete violations by class: meaningful images with missing or empty alt text; form fields labeled only by placeholder text (no `label` element paired to the input's `id` via `for`); heading order that jumps levels; keyboard and focus failures (a `div` or `span` styled and clicked like a button with no `role`, `tabindex`, or key handling); missing or wrong landmark structure (`header`/`nav`/`main`/`footer`); and contrast problems where the colors are derivable from the code. Also classify genuinely decorative images — those must carry `alt=\"\"`, not a description. Record every violation with the exact file, the concrete issue, and a priority (high/medium/low by user harm). Do not fix anything in this phase, and never pad the list — where an area is clean, say so honestly.\n\nWrite `{{workPath}}/audit.md` with exactly these sections: `## Scope` (which pages and files you exercised, with backtick paths), `## Violations` (a markdown table with columns `| File | Issue | Priority |`, one row per violation), `## Priorities` (the fix order and why). Every path you cite must be real.\n\nObservable handoff: write the completed result to `{{workPath}}/audit.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": "accessibility reviewer",
+      "capabilityFloor": "small",
+      "advanceWhen": {
+        "file": "{{workPath}}/audit.md",
+        "minBytes": 600,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "artifact": true,
+        "goto": "fix"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/audit.md",
+            "bytes": 600,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/audit.md",
+            "sniff": "nonempty",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/audit.md",
+            "pattern": "^##\\s+Scope",
+            "flags": "im",
+            "label": "Scope section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/audit.md",
+            "pattern": "^##\\s+Violations",
+            "flags": "im",
+            "label": "Violations section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/audit.md",
+            "pattern": "^##\\s+Priorities",
+            "flags": "im",
+            "label": "Priorities section",
+            "artifact": true
+          },
+          {
+            "kind": "tableShape",
+            "file": "{{workPath}}/audit.md",
+            "requiredColumns": [
+              "File",
+              "Issue",
+              "Priority"
+            ],
+            "minRows": 1,
+            "artifact": true
+          },
+          {
+            "kind": "citationsResolve",
+            "file": "{{workPath}}/audit.md",
+            "minCitations": 2,
+            "artifact": true
+          }
+        ],
+        "onReject": "audit",
+        "maxAttempts": 4
+      },
+      "next": "fix"
+    },
+    {
+      "id": "fix",
+      "name": "Fix each violation at its real site",
+      "description": "Repair every audited violation in the actual markup, styles, or components — semantic elements over ARIA bolt-ons.",
+      "prompt": "Read `{{workPath}}/audit.md` and repair every violation at its REAL site in the markup, styles, or components. There is no prescribed output path for the repairs — edit the actual files from the audit with `read_file` plus `write_file`/`replace_in_file`. Choose the semantic fix over the ARIA bolt-on: a real `button` element rather than `role` and `tabindex` sprayed on a `div` (where the surrounding code allows it), a real `label` paired to the input's `id` via `for` rather than placeholder text doing a label's job, corrected heading levels that restore monotonic order rather than CSS that fakes it. Write meaningful, specific alt text for images that carry content; give genuinely decorative images `alt=\"\"` and state why each is decorative. Keep existing behavior working — handlers, ids, and styling hooks on elements you touch must still be wired afterwards. A violation you deliberately leave unfixed gets an honest deferral with a reason, never silence.\n\nThen write `{{workPath}}/fix-notes.md` with exactly these sections: `## Problem` (one paragraph), `## Change` (what you altered, per class of violation), `## Files touched` (backtick path per line), `## Per-violation disposition` (every audit row: fixed or deferred, with the reason), `## Risk` (what could still be wrong; be honest about anything unverified), `## How to verify` (concrete steps a person follows to confirm, keyboard included). Before working, open `{{workPath}}/audit.md` with `read_artifact`.\n\nObservable handoff: write the completed result to `{{workPath}}/fix-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": "frontend engineer",
+      "capabilityFloor": "small",
+      "consumes": [
+        {
+          "file": "{{workPath}}/audit.md",
+          "artifact": true
+        }
+      ],
+      "advanceWhen": {
+        "file": "{{workPath}}/fix-notes.md",
+        "minBytes": 700,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "artifact": true,
+        "goto": "validate"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/fix-notes.md",
+            "bytes": 700,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/fix-notes.md",
+            "sniff": "nonempty",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/fix-notes.md",
+            "pattern": "^##\\s+Problem",
+            "flags": "im",
+            "label": "Problem section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/fix-notes.md",
+            "pattern": "^##\\s+Change",
+            "flags": "im",
+            "label": "Change section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/fix-notes.md",
+            "pattern": "^##\\s+Files touched",
+            "flags": "im",
+            "label": "Files touched section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/fix-notes.md",
+            "pattern": "^##\\s+Per-violation disposition",
+            "flags": "im",
+            "label": "Per-violation disposition section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/fix-notes.md",
+            "pattern": "^##\\s+Risk",
+            "flags": "im",
+            "label": "Risk section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/fix-notes.md",
+            "pattern": "^##\\s+How to verify",
+            "flags": "im",
+            "label": "How to verify section",
+            "artifact": true
+          },
+          {
+            "kind": "citationsResolve",
+            "file": "{{workPath}}/fix-notes.md",
+            "minCitations": 2,
+            "artifact": true
+          }
+        ],
+        "onReject": "fix",
+        "maxAttempts": 4
+      },
+      "next": "validate"
+    },
+    {
+      "id": "validate",
+      "name": "Validate every fix",
+      "description": "Re-inspect each fixed item against the current markup and walk the keyboard path, honest about inspected versus exercised.",
+      "prompt": "Verify with fresh eyes. Read `{{workPath}}/audit.md` and `{{workPath}}/fix-notes.md`, then re-open every touched file with `read_file` and check each audit row against the current markup: is the alt text present and specific, does each `label`'s `for` resolve to a real input `id`, is the heading sequence monotonic now, does the once-div control carry real button semantics and keyboard operability, are the landmarks in place. Walk the keyboard path as far as the code lets you: trace tab order, focusability, and key handlers through the markup and scripts. Say plainly which items you INSPECTED (read the code) versus EXERCISED (actually ran or interacted with) — anything that is neither is unverified, and you must say so rather than claim it.\n\nWrite `{{workPath}}/validation.md` with exactly these sections: `## Per-item verification` (each audit row and what you found in the current file), `## Keyboard walk` (the path a keyboard user takes and where focus goes), `## Result` (all clear, or what remains open and why). Before working, open `{{workPath}}/audit.md`, `{{workPath}}/fix-notes.md` with `read_artifact`.\n\nObservable handoff: write the completed result to `{{workPath}}/validation.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": "accessibility reviewer",
+      "capabilityFloor": "small",
+      "consumes": [
+        {
+          "file": "{{workPath}}/audit.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/fix-notes.md",
+          "artifact": true
+        }
+      ],
+      "advanceWhen": {
+        "file": "{{workPath}}/validation.md",
+        "minBytes": 500,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "artifact": true,
+        "goto": "evaluate"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/validation.md",
+            "bytes": 500,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/validation.md",
+            "sniff": "nonempty",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/validation.md",
+            "pattern": "^##\\s+Per-item verification",
+            "flags": "im",
+            "label": "Per-item verification section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/validation.md",
+            "pattern": "^##\\s+Keyboard walk",
+            "flags": "im",
+            "label": "Keyboard walk section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/validation.md",
+            "pattern": "^##\\s+Result",
+            "flags": "im",
+            "label": "Result section",
+            "artifact": true
+          },
+          {
+            "kind": "citationsResolve",
+            "file": "{{workPath}}/validation.md",
+            "minCitations": 2,
+            "artifact": true
+          }
+        ],
+        "onReject": "validate",
+        "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}}/validation.md`, `{{workPath}}/audit.md`, `{{workPath}}/fix-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. Every violation in audit.md is either fixed at its real site or honestly deferred with a stated reason — open the touched files and check the current markup; do not grade from fix-notes.md alone.\n2. No accessibility theater: where a semantic element was the right fix (a real button, a real label), the markup uses it — aria-label sprayed over a non-semantic element does not pass.\n3. Every label's for attribute resolves to a real input id in the current markup, and placeholder text no longer stands in for a label.\n4. The heading sequence in the fixed markup is monotonic — no level is skipped on the way down.\n5. Meaningful images carry specific, non-empty alt text; genuinely decorative images carry alt=\"\" with the decorative call stated in the notes.\n6. The dispositions reconcile across audit.md, fix-notes.md, and validation.md — the same items, none silently dropped — and validation.md separates inspected from exercised honestly.\n\nOpen `{{workPath}}/validation.md`, `{{workPath}}/audit.md`, `{{workPath}}/fix-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": "accessibility reviewer",
+      "consumes": [
+        {
+          "file": "{{workPath}}/validation.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/audit.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/fix-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}}/validation.md`, `{{workPath}}/audit.md`, `{{workPath}}/fix-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}}/validation.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.",
+      "suggestedRole": "frontend engineer",
+      "consumes": [
+        {
+          "file": "{{workPath}}/review.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/validation.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/audit.md",
+          "artifact": true
+        },
+        {
+          "file": "{{workPath}}/fix-notes.md",
+          "artifact": true
+        }
+      ],
+      "advanceWhen": {
+        "file": "{{workPath}}/validation.md",
+        "minBytes": 500,
+        "sniff": "nonempty",
+        "requireChange": true,
+        "artifact": true,
+        "goto": "evaluate"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/validation.md",
+            "bytes": 500,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/validation.md",
+            "sniff": "nonempty",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/validation.md",
+            "pattern": "^##\\s+Per-item verification",
+            "flags": "im",
+            "label": "Per-item verification section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/validation.md",
+            "pattern": "^##\\s+Keyboard walk",
+            "flags": "im",
+            "label": "Keyboard walk section",
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/validation.md",
+            "pattern": "^##\\s+Result",
+            "flags": "im",
+            "label": "Result section",
+            "artifact": true
+          },
+          {
+            "kind": "citationsResolve",
+            "file": "{{workPath}}/validation.md",
+            "minCitations": 2,
+            "artifact": true
+          }
+        ],
+        "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}}/validation.md`, `{{workPath}}/audit.md`, `{{workPath}}/fix-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": "small",
+  "version": "2.0.0",
+  "releasedAt": "2026-08-24T00:00:00.000Z",
+  "minGezelVersion": "1.26236"
+}