axstack 0.53.1 → 0.55.0

package/skills/axstack/scripts/fleet-sample.js

@@ -0,0 +1,48 @@
+import { parseProc, pressure } from './fleet-proc.js';
+import { validateManifest, sampleOptions } from './fleet-sample-manifest.js';
+import { readProc, wait } from './fleet-sample-io.js';
+export { parseProc, pressure, validateManifest };
+
+// Read functions and clocks are injectable for deterministic offline verification.
+export async function sampleFleet(manifest, hosts, options, dependencies = {}) {
+  validateManifest(manifest, hosts);
+  const { intervalMs, timeoutMs } = sampleOptions(options);
+  const { clock = Date.now, monotonic = () => performance.now(), read = readProc, wait: pause = wait,
+    signal } = dependencies;
+  const telemetry = await Promise.all(manifest.hosts.map(async (host) => {
+    const controller = new AbortController();
+    const cancel = () => controller.abort(Error('cancelled'));
+    signal?.addEventListener('abort', cancel, { once: true });
+    if (signal?.aborted) cancel();
+    const timer = setTimeout(() => controller.abort(Error('timeout')), timeoutMs);
+    const windowStartedAt = clock(); const started = monotonic();
+    const source = host.transport === 'local' ? 'linux-proc-local' : 'linux-proc-ssh';
+    const provenance = { hostId: host.hostId, environmentId: host.environmentId, scope: 'whole-host', source,
+      intervalMs, timeoutMs, windowStartedAt, windowKind: 'collector-bracket' };
+    const check = () => { if (controller.signal.aborted) throw controller.signal.reason; };
+    try {
+      check();
+      const first = parseProc(await read(host, controller.signal));
+      check();
+      await pause(intervalMs, controller.signal);
+      check();
+      const last = parseProc(await read(host, controller.signal));
+      check();
+      const windowEndedAt = clock(); const durationMs = Math.floor(monotonic() - started);
+      if (durationMs >= timeoutMs) throw Error('timeout');
+      if (durationMs < intervalMs || windowEndedAt < windowStartedAt
+        || windowEndedAt - windowStartedAt < durationMs
+        || windowEndedAt - windowStartedAt > durationMs + 1000) throw Error('collector-clock');
+      return { ...provenance, status: 'ok', ...pressure(first, last), durationMs,
+        windowEndedAt, receivedAt: windowEndedAt };
+    } catch (error) {
+      const reason = controller.signal.aborted ? controller.signal.reason?.message : error.message;
+      return { ...provenance, status: ['timeout', 'cancelled', 'malformed', 'inconsistent-counters', 'collector-clock']
+        .includes(reason) ? reason : 'failed', durationMs: Math.max(0, Math.floor(monotonic() - started)), receivedAt: clock() };
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', cancel);
+    }
+  }));
+  return { schemaVersion: 1, telemetry };
+}

package/skills/axstack/scripts/resolve-models.js

@@ -3,6 +3,7 @@ import { readFileSync } from 'node:fs';
 const bindings = { codex: 'codex', claude: 'claudeAgent', grok: 'grok' };
 const effortIds = { codex: 'reasoningEffort', claude: 'effort', grok: 'reasoningEffort' };
 const nonempty = (value) => typeof value === 'string' && value.trim().length > 0;
+const optionValues = (option) => option.values ?? option.options?.map((value) => value.id);
 
 function argumentsFrom(args) {
   const options = { excluded: [] };
@@ -37,9 +38,11 @@ function providerFrom(catalog, provider) {
   }
   const instance = matches[0];
   if (!Array.isArray(instance.models) || instance.models.some((model) =>
-    !model || !nonempty(model.id) || !Array.isArray(model.options) || model.options.some((option) =>
+    !model || !nonempty(model.id) || !Array.isArray(model.options ?? []) || (model.options ?? []).some((option) =>
       !option || !nonempty(option.id) || (option.options !== undefined &&
-        (!Array.isArray(option.options) || option.options.some((value) => !value || !nonempty(value.id))))))) {
+        (!Array.isArray(option.options) || option.options.some((value) => !value || !nonempty(value.id))))
+      || (option.values !== undefined && (!Array.isArray(option.values)
+        || option.values.some((value) => typeof value !== 'boolean' && !nonempty(value))))))) {
     throw new Error('malformed capabilities models or options');
   }
   return instance;
@@ -58,6 +61,7 @@ function modelFrom(models, { provider, model: pin, class: modelClass, excluded }
     }
     const model = models[0];
     if (!model || excluded.includes(model.id)) throw new Error('missing first listed model');
+    if (!model.id.startsWith('grok-')) throw new Error(`first listed model ${model.id} is not grok-family`);
     return model;
   }
   if (!['codex', 'claude'].includes(provider) || !/^[a-z]+$/.test(modelClass)) {
@@ -90,8 +94,8 @@ try {
   if ((options.class === 'terra' || /^gpt-\d+(?:\.\d+)*-terra$/.test(model.id)) && effort !== 'high') {
     throw new Error('Terra requires exactly high effort');
   }
-  const effortOptions = model.options.filter((option) => option.id === effortIds[provider]);
-  if (effortOptions.length !== 1 || !effortOptions[0].options?.some((value) => value.id === effort)
+  const effortOptions = (model.options ?? []).filter((option) => option.id === effortIds[provider]);
+  if (effortOptions.length !== 1 || !optionValues(effortOptions[0])?.includes(effort)
     || (provider === 'grok' && effort === 'max')) {
     throw new Error(`unsupported effort ${effort} for ${provider}/${model.id}`);
   }

package/skills/axstack-review/references/review-candidate.md

@@ -137,7 +137,7 @@ This section applies to peer and authored PR modes.
    For an `axstack-verify create` PR, the reviewer drives the candidate's recipe because the base has none.
    The author never performs this review drive.
    The reviewer drives each affected feature and records that drive as the `Final-head check`.
-   Delegate browser drives to `axstack-ui-verifier` with the feature file path.
+   Delegate browser drives to `axstack-ui-verifier` with the feature file path; device drives follow [UI verification](../../axstack/references/ui-verification.md#android-device-and-webpwa-dual-run)'s dual-run trigger.
    Running the applicable surface counts as spin-up; a CLI run qualifies.
    Use loopback and isolated instances under [axstack-verify](../../axstack-verify/SKILL.md#isolate-every-attempt).
 

package/skills/axstack-spec/SKILL.md

@@ -43,8 +43,9 @@ and the lifecycle's [audit skill](../axstack-audit/SKILL.md) hook.
    access before any issue write. Record the repository and identity checked.
    Missing access preserves the GitHub selection and stops the phase without
    mutation or fallback. Markdown mode skips external access preflight.
-3. **Draft with decision evidence.** Write observable acceptance criteria
-   and explicit exclusions in the selected store. Only when the scope identity
+3. **Draft with decision evidence.** Follow the
+   [readable specification format](references/format.md) when drafting in the
+   selected store. Only when the scope identity
    carries a sketch, include the [design lens](../axstack/references/design-lens.md)
    sketch in the approved revision's `Design` section and its `Usage` line in
    acceptance. First record the driver's
@@ -90,7 +91,8 @@ and the lifecycle's [audit skill](../axstack-audit/SKILL.md) hook.
    [Diligence](../axstack/references/diligence.md) to check the draft against
    the Align decisions for anything dropped, added, or softened.
 5. **Snapshot the baseline.** Record the approved revision identity and a
-   concise repository Markdown counterpart. In Linear mode, the native
+   concise repository Markdown counterpart pointing to the same requirements,
+   not a second human or agent contract. In Linear mode, the native
    document remains authoritative. In GitHub mode, the approved issue body is
    authoritative and its GitHub issue URL plus SHA-256 body digest identifies
    the exact approved revision. In Markdown mode, the agreed repository path does.

package/skills/axstack-spec/references/format.md

@@ -0,0 +1,88 @@
+# Readable specification format
+
+Use this structure inside the selected authoritative store. It changes layout,
+not store selection, adviser review, diligence, approval or snapshot authority.
+
+## Decision brief
+
+Begin with a decision brief before execution detail and history.
+Keep identity and status compact, with review-round history after current requirements.
+For example: title, revision, draft or approved status, authoritative location.
+
+- In the opening, explain the problem, why it matters and the proposed change.
+- When useful, include a concrete before/after example or flow in the opening.
+- State included and excluded scope in the brief.
+- Surface consequential risks, trade-offs and unverified boundaries in the brief.
+- Collect all decisions needed from the user in the opening, with options and
+  consequences; say explicitly when none remain.
+
+Give enough context for an informed decision. Link each consequential choice
+or risk to its precise execution requirement. Never bury a material decision
+or risk only in supporting detail.
+
+## Execution requirements
+
+Group precise requirements and observable acceptance by capability, using stable
+IDs where useful. Include behavior, interfaces, data, invariants, failure cases
+and validation that determine success. Put routine file-by-file task and PR
+sequencing in Tickets, retaining meaningful design and rollout constraints in the spec.
+State each rule once and reference it from other sections.
+Technical execution detail remains binding wherever stored, including linked detail.
+Human and agent views share one authoritative specification.
+Resolve brief/detail conflicts before approval rather than declaring one view expendable.
+
+Use headings, short requirement blocks or lists for scanning. Use a table when
+it helps compare choices, rather than putting whole paragraphs in cells.
+Do not impose word caps, mandatory tables, an extra artifact or ceremony.
+The example below is adaptable guidance, not another required document.
+The existing readback identifies and explains this same revision; it is not
+a duplicate whole spec with separate requirements.
+
+## Evidence and history
+
+Keep history, evidence and adviser receipts separate from current requirements.
+Place provenance, commands, review-round dispositions and change logs here or
+link their existing records. They explain the requirements, not override them.
+When amending a draft, update current criteria in place and keep the change log
+as history. Preserve approved snapshots immutable and mark supersession through
+metadata or links outside the approved bytes. Use the existing material-revision
+and snapshot procedure for a changed baseline; a new draft is not approval.
+
+## Readability review
+
+For readability review, verify a human can identify what changes, why, decisions
+and risks from the opening and an implementer can find exact requirements without
+reconstructing history. Assess this alongside completeness before the existing
+specification checkpoint. Return unclear or conflicting passages for revision
+under the existing review and approval rules.
+
+## Compact example
+
+```markdown
+# Export the filtered view — r2, draft
+Authoritative location: <selected store URL or repository path>
+
+## Decision brief
+Problem/why: exports ignore the table filter, forcing users to clean the file.
+Change: export what the user is viewing.
+Before: export downloads the whole dataset. After: it downloads filtered rows.
+Included: CSV export from this table. Excluded: scheduled exports and new formats.
+Trade-off/risk: an active filter can omit rows users expect; label the action
+“Export filtered rows” (EXP-1). Unverified: large exports on low-memory devices.
+Decision needed: approve filtered export with the explicit label, or retain
+whole-dataset export and its cleanup cost. Proposed choice: filtered export.
+
+## Execution requirements
+### Filtered export
+EXP-1: On click, capture the active filter and visible column order, label the
+action “Export filtered rows”, and export only matching rows in those columns.
+Acceptance for EXP-1: with a two-row dataset and a filter matching one row,
+the CSV contains that row and the visible columns in order; with a filter
+matching zero rows, the CSV contains the header only.
+
+## Evidence and history
+Source: <observed current behavior and revision>.
+Adviser receipts: <links bound to r2>; approval: pending.
+Change log: r2 incorporates the zero-row case into EXP-1 acceptance.
+Previous approved baseline, if any: <immutable ref>; supersession: pending approval.
+```

package/skills/axstack-verify/SKILL.md

@@ -49,6 +49,13 @@ Name the app, surface and invocation conditions in the description.
 - Cleanup: stop only processes started by this run and remove owned scratch.
 - Helpers: explain each helper's purpose and working directory.
 
+For a device surface, require a Device section in generated `verify-<app>` recipes.
+The Device section must use device tools to install and launch the pinned build,
+drive features, capture evidence and shutdown owned devices.
+The Device section must follow [UI verification](../axstack/references/ui-verification.md#android-device-and-webpwa-dual-run)
+for dual-run independence and reconciliation, fleet routing and desktop safety.
+Record unavailable device surfaces as unverified.
+
 Write `.agents/skills/verify-<app>/features/README.md` as an index of the top 3-5 user features.
 Write per-feature files in `.agents/skills/verify-<app>/features/` and link them from the index.
 Give each feature file its entry points, prerequisites, drive steps and observable proof.
@@ -79,10 +86,12 @@ Report an unavailable candidate run as unverified.
 
 Execute launch, doctor, drive one mapped feature, capture evidence, clean up and confirm evidence survives.
 Run doctor before each drive.
-The author drives only non-browser surfaces.
-Delegate browser drives through
-[UI verification](../axstack/references/ui-verification.md) to `axstack-ui-verifier`
+The author drives only non-browser, non-device surfaces.
+Delegate a recipe's device checks and explicitly requested app/PWA verification
+to the UI verifier roles for a dual run through
+[UI verification](../axstack/references/ui-verification.md#android-device-and-webpwa-dual-run)
 with the feature file path in the brief.
+Delegate other recipe browser drives to one `axstack-ui-verifier` pass.
 Give the verifier the pinned candidate, isolated instance and private evidence path.
 Clean up after every failed attempt.
 Retry once after a drift fix.
@@ -124,10 +133,12 @@ Classify each gap as doc drift, harness gap or product regression:
 Drive every mapped feature live even when source looks clean.
 Use the skill's Launch recipe for an isolated instance.
 Run doctor before each drive.
-The author drives only non-browser surfaces.
-Delegate browser drives through
-[UI verification](../axstack/references/ui-verification.md) to `axstack-ui-verifier`
+The author drives only non-browser, non-device surfaces.
+Delegate a recipe's device checks and explicitly requested app/PWA verification
+to the UI verifier roles for a dual run through
+[UI verification](../axstack/references/ui-verification.md#android-device-and-webpwa-dual-run)
 with the feature file path in the brief.
+Delegate other recipe browser drives to one `axstack-ui-verifier` pass.
 Capture actions, resulting states and side effects under its proof standards.
 Report unreachable prerequisites with attempted routes separately from passes.
 Fix a missing prerequisite in the map as doc drift.

package/src/roles.js

@@ -92,8 +92,8 @@ export function assessRoleReadiness(roles, preset) {
   const isIntentionalAbsence = (role) => role.model === null && (
     (preset === 'mixed' && role.id === 'axstack-research-x' && role.provider === 'grok') ||
     (preset === 'mixed' && role.id === 'axstack-arena-candidate-grok' && role.provider === 'grok') ||
-    (preset === 'codex-only' && ['axstack-advisor-opus', 'axstack-escalation-fable', 'axstack-arena-judge-opus', 'axstack-research-x', 'axstack-arena-candidate-grok', 'axstack-research-web-sol'].includes(role.id)) ||
-    (preset === 'claude-only' && ['axstack-advisor-astra', 'axstack-arena-judge-astra', 'axstack-research-x', 'axstack-arena-candidate-grok', 'axstack-auditor-sol', 'axstack-research-code-sol', 'axstack-explore-execution-sol', 'axstack-explore-codebase-luna', 'axstack-research-web-sol'].includes(role.id))
+    (preset === 'codex-only' && ['axstack-advisor-opus', 'axstack-escalation-fable', 'axstack-arena-judge-opus', 'axstack-research-x', 'axstack-arena-candidate-grok', 'axstack-research-web-sol', 'axstack-ui-verifier-sonnet'].includes(role.id)) ||
+    (preset === 'claude-only' && ['axstack-advisor-astra', 'axstack-arena-judge-astra', 'axstack-research-x', 'axstack-arena-candidate-grok', 'axstack-auditor-sol', 'axstack-research-code-sol', 'axstack-explore-execution-sol', 'axstack-explore-codebase-luna', 'axstack-research-web-sol', 'axstack-ui-verifier-sonnet'].includes(role.id))
   );
   for (const role of roles) {
     if (!bounds.has(role.provider)) {