@bendyline/gilde 0.1.40 → 0.1.41

package/authoring/gstack/overlays/investigate.json

@@ -1,4 +1,5 @@
 {
+  "frozen": true,
   "workflow": {
     "plan": "Reproduce first, diagnose second, change code only after the evidence identifies a root cause. Keep an explicit hypothesis ledger so plausible stories cannot silently become facts. Prefer the smallest experiment that separates competing explanations. The final report must connect symptom, causal mechanism, fix, and regression proof with inspectable paths and command results.",
     "phases": [

package/authoring/gstack/overlays/qa-only.json

@@ -1,4 +1,5 @@
 {
+  "frozen": true,
   "set": {
     "toolsets": [
       {

package/authoring/gstack/wave.json

@@ -26,7 +26,13 @@
       "description": "Debug systematically: reproduce the failure and find the true root cause before changing any code, then fix and verify. Enforces a no-fix-without-diagnosis discipline.",
       "tags": [
         "debugging",
-        "engineering"
+        "engineering",
+        "investigation",
+        "root-cause",
+        "incident",
+        "diagnosis",
+        "debug",
+        "memory"
       ]
     },
     {
@@ -86,7 +92,11 @@
       "description": "Exercise a running app in a real browser, triage what breaks, and produce a report-only QA findings list with a health score — no code changes.",
       "tags": [
         "qa",
-        "testing"
+        "testing",
+        "browser",
+        "manual-test",
+        "smoke-test",
+        "playwright"
       ]
     },
     {

package/authoring/tactical/books/accessibility-retrofit.json

@@ -0,0 +1,188 @@
+{
+  "id": "accessibility-retrofit",
+  "name": "Accessibility Retrofit",
+  "description": "Audit real pages for concrete accessibility violations — alt text, labels, heading order, keyboard and focus, landmarks, contrast — then fix each one at its real site in the markup and verify it, with an enforced independent review that rejects accessibility theater.",
+  "category": "code-review",
+  "role": "maintenance-review",
+  "tags": [
+    "accessibility",
+    "a11y",
+    "wcag",
+    "retrofit",
+    "html",
+    "alt-text",
+    "images"
+  ],
+  "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"
+  ],
+  "about": "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.",
+  "doc": {
+    "capabilityFloor": "small",
+    "diffpackCapable": true
+  },
+  "workflow": {
+    "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.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "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.",
+        "suggestedRole": "accessibility reviewer",
+        "capabilityFloor": "small",
+        "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.",
+        "output": {
+          "path": "{{workPath}}/audit.md",
+          "minBytes": 600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Scope",
+              "label": "Scope section"
+            },
+            {
+              "pattern": "^##\\s+Violations",
+              "label": "Violations section"
+            },
+            {
+              "pattern": "^##\\s+Priorities",
+              "label": "Priorities section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "tableShape",
+              "file": "{{workPath}}/audit.md",
+              "requiredColumns": [
+                "File",
+                "Issue",
+                "Priority"
+              ],
+              "minRows": 1,
+              "artifact": true
+            },
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/audit.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "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.",
+        "suggestedRole": "frontend engineer",
+        "capabilityFloor": "small",
+        "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).",
+        "output": {
+          "path": "{{workPath}}/fix-notes.md",
+          "minBytes": 700,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Problem",
+              "label": "Problem section"
+            },
+            {
+              "pattern": "^##\\s+Change",
+              "label": "Change section"
+            },
+            {
+              "pattern": "^##\\s+Files touched",
+              "label": "Files touched section"
+            },
+            {
+              "pattern": "^##\\s+Per-violation disposition",
+              "label": "Per-violation disposition section"
+            },
+            {
+              "pattern": "^##\\s+Risk",
+              "label": "Risk section"
+            },
+            {
+              "pattern": "^##\\s+How to verify",
+              "label": "How to verify section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/fix-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "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.",
+        "suggestedRole": "accessibility reviewer",
+        "capabilityFloor": "small",
+        "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).",
+        "output": {
+          "path": "{{workPath}}/validation.md",
+          "minBytes": 500,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Per-item verification",
+              "label": "Per-item verification section"
+            },
+            {
+              "pattern": "^##\\s+Keyboard walk",
+              "label": "Keyboard walk section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/validation.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/validation.md",
+      "relatedPaths": [
+        "{{workPath}}/audit.md",
+        "{{workPath}}/fix-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "accessibility reviewer",
+      "repairRole": "frontend engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "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.",
+        "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.",
+        "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.",
+        "The heading sequence in the fixed markup is monotonic — no level is skipped on the way down.",
+        "Meaningful images carry specific, non-empty alt text; genuinely decorative images carry alt=\"\" with the decorative call stated in the notes.",
+        "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."
+      ]
+    }
+  }
+}

package/authoring/tactical/books/apply-review-findings.json

@@ -0,0 +1,189 @@
+{
+  "id": "apply-review-findings",
+  "name": "Apply Review Findings",
+  "description": "Take an existing review's findings and close them for real: triage each one against the current code, fix the real ones at their actual sites with the smallest correct change, verify per finding, and account for every finding end to end under an enforced review.",
+  "category": "code-quality",
+  "role": "general",
+  "tags": [
+    "review-findings",
+    "follow-up",
+    "bug-fix",
+    "triage",
+    "quality",
+    "maintenance"
+  ],
+  "triggers": [
+    "apply the review findings",
+    "fix the findings",
+    "address the review",
+    "fix these issues"
+  ],
+  "about": "Close out a review the way the reviewer hoped someone would: every finding read, judged against the code as it stands TODAY, fixed at its real site or deferred with a reason a person can respect — and nothing silently dropped. First TRIAGE: read the findings (a findings JSON, a report with a findings table, or issue refs), open the cited code, and sort each finding — real, already fixed, stale, or out of scope — because reviews age and fixing a ghost is churn. Cluster the will-fix findings that belong together so one change closes them cleanly. Then FIX cluster by cluster: the smallest correct change per finding at the actual site, never a suppression or a cosmetic edit, with a per-finding disposition kept as the work happens. Then VALIDATE each addressed finding the way its report suggested — run what is runnable, probe what is probeable, and say plainly what could only be verified by reading. The enforced review then reconciles the ledger: the same finding ids must flow through triage, fix notes, and verification with consistent outcomes, because a finding lost between documents is a finding lost. Built for unattended work: findings arrive as a file or refs, dispositions come back as documents, and no runnable test suite is required. Works identically whether the run edits the project directly or drafts a change proposal for the user to apply.",
+  "doc": {
+    "paramSchema": {
+      "type": "object",
+      "properties": {
+        "findingsPath": {
+          "type": "string",
+          "title": "Findings file",
+          "description": "Artifacts-drawer path of the review findings to apply (a findings JSON array or a markdown report with a findings table). Leave empty when issueRefs or the task description carries them.",
+          "default": ""
+        },
+        "issueRefs": {
+          "type": "string",
+          "title": "Issue refs",
+          "description": "Comma-separated issue refs to address (e.g. BW-3,BW-8). Leave empty when findingsPath carries the work.",
+          "default": ""
+        }
+      }
+    },
+    "capabilityFloor": "small",
+    "diffpackCapable": true,
+    "runModes": {
+      "nightShift": "supported"
+    }
+  },
+  "workflow": {
+    "plan": "Triage every finding against the current code (real, already fixed, stale, out of scope) -> fix cluster by cluster at the real sites with a per-finding disposition -> verify each addressed finding the way its report suggested -> enforced review reconciles the full ledger.",
+    "maxGateAttempts": 4,
+    "maxReviewRounds": 3,
+    "phases": [
+      {
+        "id": "triage",
+        "name": "Triage the findings against current code",
+        "description": "Read every finding, judge it against the code as it stands now, and sort real work from ghosts.",
+        "suggestedRole": "code reviewer",
+        "capabilityFloor": "small",
+        "prompt": "Findings file (artifacts drawer): \"{{findingsPath}}\". Issue refs: \"{{issueRefs}}\". When both are empty, the task description carries the findings.\n\nRead every finding before fixing anything. Use `read_artifact` for the findings file when one is named; otherwise take the findings from the refs or the task description. Then judge each finding against the code as it stands NOW — open the cited files with `read_file` — and sort it: REAL (the problem is present today), ALREADY FIXED (the code moved on), STALE (the cited site no longer exists or the finding no longer applies), or OUT OF SCOPE (real but not this task's to change — say whose it is). Reviews age; never fix a ghost. Give every finding a stable id — keep the ids the findings already carry, or number them F-1, F-2, ... in reading order — and carry those ids through every later document. Cluster the will-fix findings that belong together so one change closes them cleanly. If the findings source cannot be found or holds no findings, record that honestly and stop rather than inventing work.\n\nWrite `{{workPath}}/triage.md` with exactly these sections: `## Findings read` (every finding: id, one-line summary, the cited site as a backtick path), `## Will fix` (the ids, each with the problem confirmed in the current code), `## Deferred` (the ids with an honest reason: already fixed, stale, or out of scope — write None when everything is real), `## Clusters` (which will-fix ids travel together and why).",
+        "output": {
+          "path": "{{workPath}}/triage.md",
+          "minBytes": 600,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Findings read",
+              "label": "Findings read section"
+            },
+            {
+              "pattern": "^##\\s+Will fix",
+              "label": "Will fix section"
+            },
+            {
+              "pattern": "^##\\s+Deferred",
+              "label": "Deferred section"
+            },
+            {
+              "pattern": "^##\\s+Clusters",
+              "label": "Clusters section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/triage.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "fix",
+        "name": "Fix cluster by cluster at the real sites",
+        "description": "The smallest correct change per finding, at the actual cited site, with a per-finding disposition ledger.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Read `{{workPath}}/triage.md` and work the will-fix clusters one at a time, at the real sites. There is no prescribed output path for source changes — edit the actual files the findings point at with `read_file` plus `write_file`/`replace_in_file`. For each finding, make the smallest correct change that genuinely fixes what the finding describes — not a suppression, not a comment, not a workaround that leaves the problem alive. Keep surrounding behavior intact: a findings pass that breaks the neighborhood trades one review for another. Keep the per-finding ledger as you go. If a finding turns out unfixable as described, move it to a deferral with the honest reason instead of pretending — never claim a fix you did not make.\n\nWrite `{{workPath}}/fix-notes.md` with exactly these sections: `## Problem` (one paragraph: what this findings pass covered), `## Change` (per cluster: what you altered and why it closes those findings), `## Files touched` (backtick path per line), `## Per-finding disposition` (every id from triage: fixed at which path, or deferred with the reason), `## Risk` (what could break, honestly), `## How to verify` (per finding: the check its report suggested, or the closest runnable equivalent).",
+        "output": {
+          "path": "{{workPath}}/fix-notes.md",
+          "minBytes": 700,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Problem",
+              "label": "Problem section"
+            },
+            {
+              "pattern": "^##\\s+Change",
+              "label": "Change section"
+            },
+            {
+              "pattern": "^##\\s+Files touched",
+              "label": "Files touched section"
+            },
+            {
+              "pattern": "^##\\s+Per-finding disposition",
+              "label": "Per-finding disposition section"
+            },
+            {
+              "pattern": "^##\\s+Risk",
+              "label": "Risk section"
+            },
+            {
+              "pattern": "^##\\s+How to verify",
+              "label": "How to verify section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/fix-notes.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      },
+      {
+        "id": "validate",
+        "name": "Verify each finding the way its report suggested",
+        "description": "Re-check every addressed finding at its site, run what is runnable, and restate the deferrals.",
+        "suggestedRole": "software engineer",
+        "capabilityFloor": "small",
+        "prompt": "Re-check every addressed finding the way its report suggested. Read `{{workPath}}/fix-notes.md`, then verify each fixed finding at its site: re-read the changed code, and run what is runnable — the project's own scripts, or a small probe when a script-execution tool such as `run_nodejs_script` is wired this turn. When nothing is runnable, verify by reading and say so plainly — an unrun check is recorded as unverified, never claimed. Confirm the deferred findings still carry their reasons. Every finding id from triage must appear here with its outcome; a finding that vanished between documents is a finding dropped.\n\nWrite `{{workPath}}/validation.md` with exactly these sections: `## Per-finding verification` (every id: how it was re-checked and what was observed, with deferrals restated), `## Result` (closed versus deferred counts, what was verified by running versus by reading, and anything still owed).",
+        "output": {
+          "path": "{{workPath}}/validation.md",
+          "minBytes": 450,
+          "requiredPatterns": [
+            {
+              "pattern": "^##\\s+Per-finding verification",
+              "label": "Per-finding verification section"
+            },
+            {
+              "pattern": "^##\\s+Result",
+              "label": "Result section"
+            }
+          ],
+          "additionalChecks": [
+            {
+              "kind": "citationsResolve",
+              "file": "{{workPath}}/validation.md",
+              "minCitations": 2,
+              "artifact": true
+            }
+          ]
+        }
+      }
+    ],
+    "review": {
+      "artifactPath": "{{workPath}}/validation.md",
+      "relatedPaths": [
+        "{{workPath}}/triage.md",
+        "{{workPath}}/fix-notes.md"
+      ],
+      "reviewPath": "{{workPath}}/review.md",
+      "reviewerRole": "findings auditor",
+      "repairRole": "software engineer",
+      "minReviewBytes": 400,
+      "enforce": {
+        "fixStepId": "repair"
+      },
+      "criteria": [
+        "Every finding from the source appears in triage.md's Findings read with an id and a cited site — count them against the findings source; a finding missing from the ledger is an automatic REVISE.",
+        "Each Will fix finding is genuinely addressed at a real site: open the touched files and confirm the change fixes what the finding describes, not a suppression, comment, or cosmetic edit.",
+        "Each Deferred finding carries an honest, specific reason (already fixed, stale, or out of scope) that holds up when you open the cited code.",
+        "The ledger reconciles: the same ids flow through triage.md, fix-notes.md's Per-finding disposition, and validation.md's Per-finding verification with consistent outcomes — no finding silently dropped or relabeled between documents.",
+        "validation.md re-checked each addressed finding the way its report suggested where runnable, and plainly labels anything verified only by reading — nothing claimed run that was not.",
+        "Every path cited across the three documents exists in this project, and fix-notes.md's Files touched matches the changes actually made."
+      ]
+    }
+  }
+}