feat(ops): URL param parsing + chip-state-from-URL (A3c, final A3)

A3c of docs/specs/ops-workflows-page-refinement/. Final piece of the
A3 implementation. Mirror of Specs page A3c (PR #539).

What changes in workflows_refined.js:

- New readURLState() — parses ?bucket=…&q=… on init. Bucket
  values are filtered against VALID_BUCKETS so invalid params
  fall through to defaults (no zero-chip lockout). Search value
  is taken verbatim.
- New bucketsAreDefault() — returns true when all 7 buckets are
  on. Used by syncURL() to keep "clean" URLs short.
- New syncURL() — called after every state change (chip toggle,
  search input). Uses history.replaceState so toggles don't
  pollute the back button. Defaults are normalized OUT of the
  URL — share a link from default state and you get bare
  /workflows.
- syncChipsToState() — new helper called in init() AFTER
  readURLState(). The server-rendered HTML has all chips
  chip-active; URL params may have flipped some off. This brings
  visual state in line with the logical state on first paint.
- init() reorders: readURLState → syncChipsToState → wireChips →
  wireSearch → set input.value → applyFilters. Chip handlers
  now also call syncURL() after applyFilters().

URL schema:

  ?bucket=review,audit  → only review + audit chips active
  ?q=security           → search prefilled with "security"
  ?bucket=review&q=auth → combine both
  (no params)            → defaults (all 7 buckets, empty search)

Bucket values are sorted in the URL for stability (toggle order
doesn't affect the generated link).

Older browsers silently fall through to default state if URL or
history APIs are unavailable — no UX regression.

Tests (9 new):

tests/unit/ops/test_workflows_refined_js.py gains a TestURLStateSurface
class covering:

- readURLState / syncURL / bucketsAreDefault on the public namespace
- ?bucket= parsing (searchParams.get("bucket"))
- ?q= parsing (searchParams.get("q"))
- replaceState used (not pushState) — no history pollution
- Defaults removed from URL (delete("bucket") + delete("q"))
- syncURL called from chip + search handlers (>= 2 occurrences)
- init() calls readURLState()

All 60 Workflows-page tests pass (A2 + A3a + A3b + A3c combined).

Spec progression now complete:
- A1 — module (#552)
- A2 — route (#553)
- A3a — chips + pill + JS (#554)
- A3b — kebab menu (#555)
- A3c — URL params (this PR — final A3)

After this stack merges, the /workflows route fully mirrors the
just-shipped /specs page UX. Worth a v7.3.1 patch when combined
with Phase 6 of sdk-error-message-fidelity (#551, merged).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: silversurfer562

src/attune/ops/static/js/workflows_refined.js

@@ -1,7 +1,9 @@
-// Workflows page — concern-chip filter + search behavior (A3a).
+// Workflows page — concern-chip filter + search + URL state (A3a + A3c).
 //
 // Reads the server-rendered table at /workflows and applies client-side
-// filtering by concern bucket + workflow name substring.
+// filtering by concern bucket + workflow name substring. URL state
+// (?bucket=…&q=…) is the source of truth — JS reads on init, writes
+// on chip toggle / search input.
 //
 // Default state per docs/specs/ops-workflows-page-refinement/decisions.md D1/D2:
 //   - All 7 concern chips active (no chip is structurally "noise"
@@ -11,8 +13,6 @@
 // No sort dropdown — workflows render alphabetical by name from the
 // server (decisions.md D7: alphabetical-by-name; v2 may add by-last-run).
 //
-// URL params ship in A3c. A3b adds the kebab action menu.
-//
 // Exports a `window.__attuneWorkflows` namespace so future PRs and
 // source-grep tests can verify the surface (matches the
 // `__attuneSpecs` + `__attuneRunner` convention).
@@ -38,6 +38,73 @@
     search: "",
   };
 
+  // ---------- URL state (A3c) ----------
+  //
+  // ?bucket=review,audit&q=security  → state.buckets={review,audit}, search="security"
+  //
+  // Defaults are normalized OUT of the URL — a "clean" URL (no params)
+  // means "default state: all buckets, no search". This keeps shared
+  // links short and survives back/forward navigation cleanly.
+
+  function readURLState() {
+    try {
+      var u = new URL(window.location.href);
+      var bucketParam = u.searchParams.get("bucket");
+      if (bucketParam !== null && bucketParam.length > 0) {
+        var candidates = bucketParam
+          .split(",")
+          .map(function (b) {
+            return b.trim();
+          })
+          .filter(function (b) {
+            return VALID_BUCKETS.has(b);
+          });
+        // Empty after filtering → invalid param, fall back to defaults
+        // (don't strand the user with zero chips active on first paint).
+        if (candidates.length > 0) {
+          state.buckets = new Set(candidates);
+        }
+      }
+      var q = u.searchParams.get("q");
+      if (q !== null) {
+        state.search = q;
+      }
+    } catch (e) {
+      // URL parse failure in older browsers / restrictive contexts —
+      // silent fall-through to defaults is fine, no UX regression.
+    }
+  }
+
+  function bucketsAreDefault(bucketSet) {
+    // "Default" = all 7 buckets on. URL stays clean in that case.
+    return bucketSet.size === VALID_BUCKETS.size;
+  }
+
+  function syncURL() {
+    try {
+      var u = new URL(window.location.href);
+      if (bucketsAreDefault(state.buckets)) {
+        u.searchParams.delete("bucket");
+      } else {
+        // Sort for stable URLs — same bucket set always serializes the
+        // same way regardless of toggle order.
+        var sorted = Array.from(state.buckets).sort();
+        u.searchParams.set("bucket", sorted.join(","));
+      }
+      var q = (state.search || "").trim();
+      if (q.length === 0) {
+        u.searchParams.delete("q");
+      } else {
+        u.searchParams.set("q", q);
+      }
+      // Use replaceState — toggling a chip shouldn't push a history
+      // entry per toggle. Back button still leaves /workflows entirely.
+      window.history.replaceState({}, "", u.toString());
+    } catch (e) {
+      // Older browser — silent no-op (state still works, just no URL sync).
+    }
+  }
+
   // ---------- DOM helpers ----------
 
   function $(sel) {
@@ -139,6 +206,7 @@
           setChipState(chip, true);
         }
         applyFilters();
+        syncURL();
       });
     });
   }
@@ -149,20 +217,35 @@
     input.addEventListener("input", function () {
       state.search = input.value;
       applyFilters();
+      syncURL();
     });
   }
 
   // ---------- Init ----------
 
+  function syncChipsToState() {
+    // After readURLState() runs, the visual chip state may not match
+    // what state.buckets says. Server-rendered HTML has all chips
+    // chip-active; URL params may have flipped some off. This brings
+    // visual state in line with the logical state on first paint.
+    $$(".workflows-toolbar .chip[data-bucket]").forEach(function (chip) {
+      var bucket = chip.getAttribute("data-bucket");
+      setChipState(chip, state.buckets.has(bucket));
+    });
+  }
+
   function init() {
+    // A3c — URL state is the source of truth on init. Read it before
+    // wiring handlers so the first handler invocation already sees
+    // the URL-derived state.
+    readURLState();
+    syncChipsToState();
     wireChips();
     wireSearch();
-    // First-paint render — server already filtered nothing, but the
-    // empty-state logic needs to run in case there's a stored search
-    // (browser back/forward restored the input value).
+    // Sync the search <input>'s value to the URL-derived state.
     var input = $("#workflows-search");
-    if (input && input.value) {
-      state.search = input.value;
+    if (input) {
+      input.value = state.search;
     }
     applyFilters();
   }
@@ -180,6 +263,9 @@
     state: state,
     applyFilters: applyFilters,
     setChipState: setChipState,
+    readURLState: readURLState,
+    syncURL: syncURL,
+    bucketsAreDefault: bucketsAreDefault,
     init: init,
   };
 })();

tests/unit/ops/test_workflows_refined_js.py

@@ -143,3 +143,56 @@ def test_template_loads_workflows_refined_js(self) -> None:
         )
         template_text = template_path.read_text(encoding="utf-8")
         assert "workflows_refined.js" in template_text
+
+
+class TestURLStateSurface:
+    """A3c — URL param parsing + state sync.
+
+    The JS module exposes readURLState/syncURL on the namespace and
+    wires them into chip + search handlers so ?bucket=…&q=… is the
+    source of truth on init and updates as the user toggles.
+    """
+
+    def test_exposes_read_url_state(self, js_text: str) -> None:
+        """readURLState is on the public surface."""
+        assert "readURLState" in js_text
+
+    def test_exposes_sync_url(self, js_text: str) -> None:
+        """syncURL is on the public surface."""
+        assert "syncURL" in js_text
+
+    def test_exposes_buckets_are_default(self, js_text: str) -> None:
+        """bucketsAreDefault helper for clean-URL detection."""
+        assert "bucketsAreDefault" in js_text
+
+    def test_parses_bucket_query_param(self, js_text: str) -> None:
+        """URL ?bucket= is read into state.buckets."""
+        assert 'searchParams.get("bucket")' in js_text
+
+    def test_parses_q_query_param(self, js_text: str) -> None:
+        """URL ?q= is read into state.search."""
+        assert 'searchParams.get("q")' in js_text
+
+    def test_uses_replace_state_not_push(self, js_text: str) -> None:
+        """Toggling a chip uses replaceState — toggles don't pollute
+        browser history.
+        """
+        assert "history.replaceState" in js_text
+
+    def test_clean_url_when_defaults(self, js_text: str) -> None:
+        """When all buckets are on and search is empty, both params
+        are removed from the URL.
+        """
+        assert 'searchParams.delete("bucket")' in js_text
+        assert 'searchParams.delete("q")' in js_text
+
+    def test_sync_url_called_on_chip_toggle(self, js_text: str) -> None:
+        """The chip click handler calls syncURL() after applyFilters()."""
+        # Pattern: applyFilters() is called, then syncURL() within the
+        # same handler. Just check syncURL() appears more than once
+        # (definition + at least one call site).
+        assert js_text.count("syncURL()") >= 2
+
+    def test_init_calls_read_url_state(self, js_text: str) -> None:
+        """init() reads URL state before wiring handlers."""
+        assert "readURLState()" in js_text