@bongos/core 1.19.806 → 1.19.808

package/docs/recipes/upgrading-the-core.md

@@ -114,6 +114,45 @@ Each subscribed instance: read its installed core → ask the registry (`npm vie
 
 **Triple-gated, so nothing moves by accident:** the `core-update-subscription` routine is `requiresAutonomy: true` + **default OFF** in [`config/scheduled-routines.json`](../../config/scheduled-routines.json), the roster ships empty, and every upgrade is health-gated. Arm it by enabling the routine's timer on the control plane once autonomy is on.
 
+#### How often it sweeps — the lag knob (task 1003674)
+
+**This timer's period IS the delay between a builder's merge and the live site
+serving it.** Everything upstream is already fast: CI publishes to npm within
+~2 minutes of a merge. The pull-deploy timer is fast too, but it watches the
+*instance repo*, not npm — it logs `already at origin/main — nothing to deploy`
+and only acts once a pin-bump commit exists. **This sweep is what creates that
+commit**, so nothing reaches the site between its runs. Left at `OnCalendar=daily`
+the worst case is ~24 hours, which is what made shipped work look unshipped and
+pushed the owner into manual go-lives.
+
+Install it at the declared cadence (`15min` in `config/scheduled-routines.json`):
+
+```ini
+# /etc/systemd/system/<instance>-core-update-subscription.timer
+[Timer]
+OnCalendar=*:0/15
+RandomizedDelaySec=120
+Persistent=true
+```
+
+```bash
+sudo systemctl daemon-reload && sudo systemctl restart <instance>-core-update-subscription.timer
+systemctl list-timers '*core-update-subscription*' --no-pager   # confirm the next elapse is minutes away
+```
+
+**Do not go below ~5 minutes.** An upgrading run takes ~2 minutes; at a tighter
+spacing runs overlap. A run with nothing to take costs one `npm view` and exits,
+so 15 minutes is cheap — the cost scales with releases, not with checks.
+
+This does **not** weaken the pinned-core model ([ADR 0108](../adr/0108-instance-composition-configurable-root.md)):
+the pin still exists, a bad release can still be frozen or rolled back, and every
+upgrade stays health-gated with auto-rollback (task 2149). A faster sweep only
+removes the wait.
+
+**Verify:** merge something, wait for the next elapse, and confirm
+`curl -s https://<instance>/version` reports the new `coreVersion` with nobody
+running a go-live.
+
 **Not covered:** multi-host / SSH orchestration across a real fleet (the deferred fleet-control-plane epic, task [#1948](https://example.com/builders#/task/1948)); and *publishing* new patches, which stays a gated owner step (ADR 0134) — a follow-up task decides whether merges auto-publish.
 
 ## Gotchas

package/modules/hall-ui/public/record.css

@@ -356,6 +356,29 @@
 
 /* ---- the actions --------------------------------------------------------- */
 .rec-actions { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; }
+
+/* task 1002858 — the shaping verbs on the task record.
+
+   The RETIRE row sits under the button row rather than in it, and is separated
+   by a rule: it is the one control on this page that destroys the plan instead
+   of advancing it, so it does not share a line with Ship it and Copy prompt. */
+.rec-actions--retire { margin: 14px 0 0; padding: 12px 0 0; border-top: var(--line) solid var(--rule-soft); }
+.td-btn--danger { color: var(--danger); border-color: var(--danger); }
+.td-btn--danger:hover:not(:disabled) { background: var(--danger-weak); color: var(--danger); border-color: var(--danger); }
+
+/* The × that cuts a dependency edge. Quiet until the row is hovered or it is
+   focused, because the list's job is to be READ — the control is for the rare
+   moment the chain is wrong, and a column of red crosses would say otherwise. */
+.rec-dep__cut {
+  flex: none; margin-left: 4px; padding: 0 6px; min-width: 24px; line-height: 20px;
+  background: none; border: var(--line) solid transparent; border-radius: var(--radius-sm);
+  color: var(--ink-faint); font-size: 15px; cursor: pointer; opacity: 0;
+}
+.rec-deplist li:hover .rec-dep__cut, .rec-dep__cut:focus-visible { opacity: 1; }
+.rec-dep__cut:hover:not(:disabled) { color: var(--danger); border-color: var(--danger); }
+.rec-dep__cut:disabled { color: var(--ink-faint); cursor: default; opacity: 1; }
+/* Touch has no hover, so the control must simply be there. */
+@media (hover: none) { .rec-dep__cut { opacity: 1; } }
 /* Where a lifecycle control would be but is not, the record says why in words.
    Nothing here is pressable-or-live, so nothing here is warm. */
 .rec-actnote { margin: 0; flex: 1 1 240px; font-size: 14px; color: var(--ink-soft); max-width: var(--measure); }

package/modules/hall-ui/public/task.js

@@ -7,10 +7,18 @@
 // the page itself (SIGNEDIN_BUILDERS_PAGE_RE + the two-segment TASK_DETAIL_PAGE_RE),
 // so an unauthenticated visitor never reaches this script.
 //
-// READ + NAVIGATION ONLY (task 751 scope) — no claim/release/ship action lives
-// here. The "Copy prompt" button is purely client-side (clipboard write, no
-// server call), same posture as the Work Board's copy action. Claim/release
-// from the browser is the dependent follow-up task.
+// NOT READ-ONLY ANY MORE, and this comment is the third thing to say so: task
+// 751 opened the page read+navigation only, task 759 added Ship it / Confirm,
+// task 1003063 added the goal move, and task 1002858 adds the task-SHAPING
+// verbs — priority, dependency add/remove, and abandon. "Copy prompt" is still
+// the only purely client-side control (a clipboard write, no server call).
+//
+// THE RULE EVERY WRITE ON THIS PAGE FOLLOWS (ADR 0016): the server owns every
+// rank and ownership gate; this file only decides which control to SURFACE, and
+// maps a refusal to a sentence. isSupervisor here is the client's read of the
+// Metic floor those permissions share (task.edit, task.abandon,
+// task.dependency.manage) — it is a display hint, never the gate. Claim/release
+// from the browser is still the dependent follow-up task.
 
 (() => {
   'use strict';
@@ -21,6 +29,9 @@
   // builds through unchanged; result-mode ({ status, ok, data }) preserves control flow 1:1.
   const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
   const AUTH_NEEDED = 'auth-needed';
+  // task 1002858 — whether the retire disclosure is expanded. Module-level
+  // because renderTask() rebuilds #task-body wholesale on every call.
+  let abandonOpen = false;
   const { escapeHtml, $, fmtDate, errCode, errMessage } = window.OTB; // task 1002462: envelope readers
   const toast = (msg) => window.OTB.toast(msg, { duration: 2600 });
   const curLabel = () => (window.__BRANDING__ && window.__BRANDING__.currency && window.__BRANDING__.currency.label) || 'credits';
@@ -84,6 +95,24 @@
     return data;
   }
 
+  // task 1002858: mutating call for removing a dependency edge. Same posture as
+  // postJSON/patchJSON — resolves to the parsed 2xx body, throws an Error carrying
+  // { status, data } so the caller can print the server's own refusal. DELETE
+  // carries no body by design; the edge to cut is named in the path.
+  async function delJSON(path) {
+    const res = await api.request('DELETE', path);
+    if (res.status === 401) { toAuth(); throw new Error('redirecting to auth'); }
+    let data = null;
+    try { data = res.data; } catch (_) { /* empty / non-JSON body */ }
+    if (!res.ok) {
+      const err = new Error(`${path} → ${res.status}`);
+      err.status = res.status;
+      err.data = data || {};
+      throw err;
+    }
+    return data;
+  }
+
   // Map the server's typed lifecycle-error to a builder-readable line. Codes are
   // exactly those POST /tasks/:id/ship + /confirm can return. The server is the
   // authority (ADR 0016); the UI only surfaces the refusal.
@@ -235,11 +264,21 @@
     return `<span class="rec-pill${tone ? ` rec-pill--${tone}` : ''}${extraClass ? ` ${extraClass}` : ''}">${escapeHtml(s)}</span>`;
   }
 
-  function depList(kindWord, items) {
+  // `removable` is passed ONLY for "Blocked by" (task 1002858), and the asymmetry
+  // is deliberate. DELETE /tasks/:id/dependencies/:depId removes the edge where
+  // THIS task depends on another, which is this record's own business. The
+  // "Blocks" list is the same edges seen from the far end: dropping one there
+  // would be editing a DIFFERENT task's dependency set from a page that is not
+  // showing it, with no sight of why that other task was made to wait. Open that
+  // task and remove it there.
+  function depList(kindWord, items, { removable = false } = {}) {
     const rows = items.map((d) => {
       const status = d.status ? statusPill(d.status, 'rec-pill--sm') : '';
+      const cut = removable
+        ? `<button class="rec-dep__cut" type="button" data-cut-dep="${escapeHtml(String(d.id))}" title="Stop waiting on task ${escapeHtml(String(d.id))}" aria-label="Stop waiting on task ${escapeHtml(String(d.id))}">×</button>`
+        : '';
       return `<li><a class="rec-dep" href="${hallBase()}/task/${escapeHtml(String(d.id))}">` +
-        `<b class="rec-dep__id">${escapeHtml(String(d.id))}</b>${escapeHtml(d.title || 'task')}</a>${status}</li>`;
+        `<b class="rec-dep__id">${escapeHtml(String(d.id))}</b>${escapeHtml(d.title || 'task')}</a>${status}${cut}</li>`;
     }).join('');
     return `<section><p class="rec-sec__h">${escapeHtml(kindWord)}</p><ul class="rec-deplist">${rows}</ul></section>`;
   }
@@ -459,6 +498,21 @@
     // gates read the same rank once, rather than risking drift between copies.
     const rank = (viewer && viewer.rank) ? String(viewer.rank).toLowerCase() : '';
     const isSupervisor = rank === 'metic' || rank === 'archon';
+    // task 1002858 — the SHAPING verbs (priority, dependencies, abandon) share one
+    // floor: task.edit, task.dependency.manage and task.abandon are all Metic+
+    // (ADR 0090; abandon re-ranked down from Archon by ADR 0152). A separate name
+    // from isSupervisor because they are separate ideas that merely agree today —
+    // if one of those permissions moves, this line moves and the lifecycle
+    // controls do not. It is a DISPLAY hint: the server re-checks every one.
+    //
+    // Goal LEAD status deliberately confers nothing here. Whether leading a goal
+    // should carry these permissions is a governance change that needs its own
+    // ADR, so this surfaces controls only for builders who already hold the atoms.
+    const canShape = isSupervisor;
+    // render() rebuilds #task-body wholesale, so a disclosure cannot keep its
+    // state in the DOM. This re-renders the SAME data without a refetch — the
+    // toggle is a view change, not a reason to ask the server anything.
+    const rerender = () => renderTask(t, lastClaim, viewer, goal, extras);
 
     const parts = [];
     parts.push(`<p class="rec-kind">Task ${statusPill(t.status)}</p>`);
@@ -520,6 +574,41 @@
       `);
     }
 
+    // task 1002858 — the two remaining SHAPING verbs, next to the goal move
+    // because they are the same kind of act: correcting how the work is routed
+    // and ordered, not moving it through its lifecycle.
+    //
+    // PRIORITY IS NOT COSMETIC, which is why it earns a control rather than a
+    // note: the DB weights version progress as `6 - COALESCE(priority, 5)` and
+    // the session optimizer orders claimable work by `priority ASC NULLS LAST`,
+    // so a wrong value at create time steers what every builder claims until
+    // someone fixes it. Until task 1003750 it was write-once at every rank and a
+    // whole-goal re-rank had to run as raw SQL. 1..5 mirrors tasks_priority_check;
+    // the empty option clears it back to unset, which is a real state (NULLS LAST)
+    // and not the same as P5.
+    if (canShape) {
+      const pOpts = ['', '1', '2', '3', '4', '5'].map((v) => {
+        const cur = t.priority == null ? '' : String(t.priority);
+        const label = v === '' ? '— unset —' : `P${v}`;
+        return `<option value="${v}"${v === cur ? ' selected' : ''}>${label}</option>`;
+      }).join('');
+      parts.push(`
+        <div class="td-form" id="shape-form">
+          <label class="td-field"><span>Priority</span>
+            <select id="priority-select">${pOpts}</select>
+          </label>
+          <label class="td-field"><span>Wait for task</span>
+            <input id="dep-add-input" type="number" min="1" step="1" inputmode="numeric" placeholder="task id">
+          </label>
+          <div class="td-actions">
+            <button type="button" class="td-btn" id="priority-btn">Set priority</button>
+            <button type="button" class="td-btn" id="dep-add-btn">Add dependency</button>
+          </div>
+          <p class="td-form-hint">A dependency keeps this task out of the claimable queue until that one ships. Remove one with the × beside it under “Blocked by”.</p>
+        </div>
+      `);
+    }
+
     const creditVal = window.OTBBranding?.taskCreditValue?.(t) ?? t.credits_reward;
     parts.push(figureBand([
       [window.OTBBranding?.taskCreditLabel?.(t) ?? curLabel(), creditVal],
@@ -577,7 +666,7 @@
     const deps = Array.isArray(t.dependencies) ? t.dependencies : [];
     const dependents = Array.isArray(t.dependents) ? t.dependents : [];
     if (deps.length || dependents.length) {
-      parts.push(`<div class="rec-sec rec-depcols">${deps.length ? depList('Blocked by', deps) : ''}${dependents.length ? depList('Blocks', dependents) : ''}</div>`);
+      parts.push(`<div class="rec-sec rec-depcols">${deps.length ? depList('Blocked by', deps, { removable: canShape }) : ''}${dependents.length ? depList('Blocks', dependents) : ''}</div>`);
     }
 
     if (t.shipped_at) {
@@ -614,6 +703,40 @@
       lifecycle = `<p class="rec-actnote">This task has shipped and its credits have landed. Neither Ship it nor Confirm is available.</p>`;
     }
 
+    // task 1002858 — RETIRE. Kept out of the button row and behind a disclosure
+    // because it is the one control here that destroys the plan rather than
+    // advancing it, and because the server demands a reason it can put in the
+    // audit log.
+    //
+    // THE TWO REFUSALS ARE PRE-ANSWERED IN WORDS RATHER THAN OFFERED AS A BUTTON
+    // THAT CANNOT WORK. A shipped task is immutable history, and a task with an
+    // active claim must be released first — both are 409s the server will raise
+    // anyway, and both are knowable from this record. Offering the control and
+    // letting it fail would teach the reader that the page guesses.
+    const claimIsLive = !!(lastClaim && !lastClaim.released_at);
+    let retire = '';
+    if (canShape && t.status === 'shipped') {
+      retire = '<p class="rec-actnote">A shipped task cannot be retired — it is immutable history now.</p>';
+    } else if (canShape && claimIsLive) {
+      retire = '<p class="rec-actnote">Someone is holding a claim on this task. It has to be released before the task can be retired.</p>';
+    } else if (canShape && t.status === 'abandoned') {
+      retire = '<p class="rec-actnote">This task is already retired. Promote restores it to the backlog.</p>';
+    } else if (canShape) {
+      retire = abandonOpen
+        ? `
+          <div class="td-form" id="abandon-form">
+            <label class="td-field td-field--wide"><span>Why retire this task?</span>
+              <input id="abandon-reason" type="text" maxlength="2000" placeholder="e.g. superseded by task 1002891">
+            </label>
+            <div class="td-actions">
+              <button type="button" class="td-btn td-btn--danger" id="abandon-btn">Retire this task</button>
+              <button type="button" class="td-btn" id="abandon-cancel-btn">Cancel</button>
+            </div>
+            <p class="td-form-hint">The reason is recorded in the audit log. This is recoverable: a retired task can be restored to the backlog with Promote.</p>
+          </div>`
+        : '<button class="td-btn" type="button" id="abandon-open-btn">Retire this task…</button>';
+    }
+
     // Copy prompt (the "ship link") — the same claim/build/ship prompt the Work
     // Board hands an agent. Purely client-side (clipboard write, no server call).
     parts.push(`
@@ -624,6 +747,7 @@
           <button class="td-btn" type="button" id="copy-prompt-btn">Copy prompt</button>
           ${exitLinkHtml()}
         </div>
+        ${retire ? `<div class="rec-actions rec-actions--retire">${retire}</div>` : ''}
       </section>
     `);
 
@@ -660,6 +784,99 @@
     // task 1003063 (R10): PATCH goal_id, then a full reload so the goal line, the
     // picker's preselected option and everything else on the record re-render
     // against the server's own state — no local patchwork of the DOM.
+    // task 1002858 — the shaping handlers. Each one: disable while in flight, send,
+    // then `load()` so the whole record re-renders against the SERVER's state
+    // rather than a local patch of the DOM (the idiom the goal move set below).
+    // Every refusal prints the server's own sentence where it has one — those are
+    // more specific than anything this page could invent, and one of them
+    // (dependency.cross_tier.manage, Archon-only under ADR 0157) names a gate this
+    // file deliberately does not model rather than re-deriving it client-side.
+    async function runWrite(btn, fn, okMsg) {
+      if (!btn || btn.disabled) return;
+      const orig = btn.textContent;
+      btn.disabled = true;
+      btn.textContent = '…';
+      try {
+        await fn();
+        toast(okMsg);
+        await load();
+      } catch (err) {
+        if (err && err.message === 'redirecting to auth') return;
+        toast(errMessage(err && err.data) || `That did not go through (${(err && err.status) || '?'}). Try again.`);
+        btn.disabled = false;
+        btn.textContent = orig;
+      }
+    }
+
+    const priorityBtn = $('#priority-btn');
+    if (priorityBtn) {
+      priorityBtn.addEventListener('click', () => {
+        const raw = $('#priority-select')?.value ?? '';
+        // '' is the unset option, and it is sent as null ON PURPOSE — "no priority"
+        // is a real state the optimizer sorts last (NULLS LAST), not a synonym for
+        // P5. Sending nothing at all would 400 as no_supported_fields.
+        const priority = raw === '' ? null : Number(raw);
+        if (priority !== null && !Number.isInteger(priority)) { toast('Pick a priority first.'); return; }
+        const was = t.priority == null ? 'unset' : `P${t.priority}`;
+        const now = priority == null ? 'unset' : `P${priority}`;
+        if (was === now) { toast(`Priority is already ${now}.`); return; }
+        runWrite(priorityBtn,
+          () => patchJSON(`${API}/tasks/${encodeURIComponent(t.id)}`, { priority }),
+          `Priority ${was} → ${now}.`);
+      });
+    }
+
+    const depAddBtn = $('#dep-add-btn');
+    if (depAddBtn) {
+      depAddBtn.addEventListener('click', () => {
+        const raw = $('#dep-add-input')?.value ?? '';
+        const depId = Number(raw);
+        if (!Number.isInteger(depId) || depId <= 0) { toast('Enter the id of the task this one should wait for.'); return; }
+        // Caught here only to say something better than the server's 'self_dep';
+        // the server still refuses it if this check is ever wrong.
+        if (String(depId) === String(t.id)) { toast('A task cannot wait for itself.'); return; }
+        runWrite(depAddBtn,
+          () => postJSON(`${API}/tasks/${encodeURIComponent(t.id)}/dependencies`, { depends_on_task_id: depId }),
+          `Task ${t.id} now waits for task ${depId}.`);
+      });
+    }
+
+    // Wired per row, because the × lives inside a list this function rebuilds on
+    // every render and the nodes are replaced with it.
+    for (const cut of document.querySelectorAll('[data-cut-dep]')) {
+      cut.addEventListener('click', () => {
+        const depId = cut.getAttribute('data-cut-dep');
+        runWrite(cut,
+          () => delJSON(`${API}/tasks/${encodeURIComponent(t.id)}/dependencies/${encodeURIComponent(depId)}`),
+          `Task ${t.id} no longer waits for task ${depId}.`);
+      });
+    }
+
+    const abandonOpenBtn = $('#abandon-open-btn');
+    if (abandonOpenBtn) {
+      abandonOpenBtn.addEventListener('click', () => { abandonOpen = true; rerender(); });
+    }
+    const abandonCancelBtn = $('#abandon-cancel-btn');
+    if (abandonCancelBtn) {
+      abandonCancelBtn.addEventListener('click', () => { abandonOpen = false; rerender(); });
+    }
+    const abandonBtn = $('#abandon-btn');
+    if (abandonBtn) {
+      abandonBtn.addEventListener('click', () => {
+        const reason = ($('#abandon-reason')?.value || '').trim();
+        // A REASON IS REQUIRED HERE THOUGH THE SERVER ACCEPTS AN EMPTY ONE. The
+        // value of the audit_log row is the sentence in it; a retire with a blank
+        // reason is the record noting that someone did this and declining to say
+        // why. Asking costs one line.
+        if (!reason) { toast('Say why it is being retired — the reason goes in the record.'); return; }
+        if (!window.confirm(`Retire task ${t.id}? It leaves the claimable queue. Promote restores it to the backlog.`)) return;
+        abandonOpen = false;
+        runWrite(abandonBtn,
+          () => postJSON(`${API}/tasks/${encodeURIComponent(t.id)}/abandon`, { reason }),
+          `Task ${t.id} retired. Promote restores it to the backlog.`);
+      });
+    }
+
     const moveGoalBtn = $('#move-goal-btn');
     if (moveGoalBtn) {
       moveGoalBtn.addEventListener('click', async () => {

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.806",
+  "version": "1.19.808",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.806",
+      "version": "1.19.808",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.806",
+  "version": "1.19.808",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/routine-schedule.js

@@ -52,11 +52,49 @@ const WORKFLOWS_DIR = path.join(ROOT, '.github', 'workflows');
 
 const { parseRoutineFrontmatter } = require('./run-routine.js');
 
-// The cadences a routine may declare. The value is the period a cron expression
-// must resolve to for the two to agree. Add a name here and cronCadence() below
-// must be able to produce it, or the pair can never match.
+// The NAMED cadences a routine may declare. The value is the period a cron
+// expression must resolve to for the two to agree. Add a name here and
+// cronCadence() below must be able to produce it, or the pair can never match.
 const CADENCES = new Set(['hourly', 'daily', 'weekly', 'monthly']);
 
+// Sub-hourly cadences are open-ended rather than enumerated: '15min', '5min',
+// '30min'. Task 1003674 found the vocabulary topped out at `hourly`, so a
+// routine an operator wants to fire every 15 minutes could not SAY so — the
+// step cron that realizes it classified as unclassifiable and hard-failed the
+// check, which left "declare nothing and stay dormant" as the only green
+// option. That is the exact failure mode this file exists to refuse.
+//
+// N MUST DIVIDE 60. A cron step restarts each hour, so only a divisor of 60
+// yields a genuinely uniform period: `*/15` fires at :00 :15 :30 :45 (every 15
+// minutes, always), but `*/7` fires at :00 …:56 and then waits 4 — a "7min"
+// cadence that is not one. Refusing the non-divisors keeps the declared period
+// and the realized period the same claim.
+const SUBHOURLY_RE = /^([1-9]\d*)min$/;
+
+// The one definition of "is N a real sub-hourly period" — both the cadence NAME
+// ('15min') and the cron STEP (*/15) are validated through here, so the two can
+// never drift apart and disagree about the same number.
+function isUniformDivisor(n) {
+  return Number.isInteger(n) && n > 0 && n < 60 && 60 % n === 0;
+}
+
+function subhourlyMinutes(name) {
+  const m = SUBHOURLY_RE.exec(String(name == null ? '' : name));
+  if (!m) return null;
+  const n = Number(m[1]);
+  return isUniformDivisor(n) ? n : null;
+}
+
+// The validity predicate the check asks. Kept separate from CADENCES so the
+// named set stays a plain enumerable list for the error message.
+function isCadence(name) {
+  return CADENCES.has(name) || subhourlyMinutes(name) !== null;
+}
+
+// The minute-field step spelling, hoisted so it is compiled once rather than per
+// classified cron: `*/15` and the equivalent `0/15`.
+const STEP_RE = /^(?:\*|0)\/([1-9]\d*)$/;
+
 // Pure: classify a 5-field cron expression into the cadence it actually realizes.
 // Returns null for anything this vocabulary cannot describe (step values, lists,
 // ranges) — a cadence can then never "match" it, which is the safe direction: an
@@ -67,12 +105,25 @@ const CADENCES = new Set(['hourly', 'daily', 'weekly', 'monthly']);
 //   17   6    *   *   *   → daily    (a specific hour, every day)
 //   17   6    3   *   *   → monthly  (a specific day-of-month)
 //   17   *    *   *   *   → hourly   (a specific minute, every hour)
+//   */15 *    *   *   *   → 15min    (a uniform sub-hourly step)
 function cronCadence(expr) {
   const f = String(expr == null ? '' : expr).trim().split(/\s+/);
   if (f.length !== 5) return null;
   const [min, hour, dom, mon, dow] = f;
   const fixed = (v) => /^\d+$/.test(v);
   const any = (v) => v === '*';
+
+  // Sub-hourly: a step in the minute field with every coarser field wide open.
+  // (STEP_RE is module-scope — see above.)
+  // Anything narrower (a step confined to one hour, or to weekdays) is NOT the
+  // period it looks like, so it stays unclassifiable.
+  const step = STEP_RE.exec(min);
+  if (step) {
+    if (!(any(hour) && any(dom) && any(mon) && any(dow))) return null;
+    const n = Number(step[1]);
+    return isUniformDivisor(n) ? `${n}min` : null;
+  }
+
   if (!fixed(min)) return null;          // every cadence below pins the minute
   if (!any(mon)) return null;            // a specific month is a yearly shape
   if (any(hour)) return any(dom) && any(dow) ? 'hourly' : null;
@@ -145,8 +196,8 @@ function evaluate({ withCadence, withoutCadence }, workflows) {
   const wf = workflows || [];
 
   for (const r of withCadence) {
-    if (!CADENCES.has(r.cadence)) {
-      violations.push(`routine '${r.name}': unknown cadence "${r.cadence}" (want ${[...CADENCES].join('|')})`);
+    if (!isCadence(r.cadence)) {
+      violations.push(`routine '${r.name}': unknown cadence "${r.cadence}" (want ${[...CADENCES].join('|')}, or <N>min where N divides 60)`);
       continue;
     }
     const firing = wf.filter((w) => invokesRoutine(w.text, r.name, r.steps));
@@ -228,4 +279,5 @@ if (require.main === module) main();
 module.exports = {
   checkRoutineCadencesScheduled, evaluate, cronCadence, workflowCrons,
   invokesRoutine, readRoutines, readWorkflows, CADENCES,
+  isCadence, subhourlyMinutes, isUniformDivisor,
 };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.806'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.808'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');