@bonesofspring/ai-rules 0.2.17 → 0.2.19

package/presets/cursor/svelte/skills/ux-design/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: ux-design
+description: Behavioral UX synthesis and review for task-analyst. Modes synthesize|review. Standalone intent ux-design or embedded required-signal / advisory UI AC. No Figma MCP; no DESIGN.md.
+---
+
+# UX design
+
+Requestable procedure for **task-analyst** (not a pipeline agent). Checklist lives in rule `ux-design` — do not duplicate it here.
+
+**Not** a Figma workflow: do not call Figma MCP; do not write `DESIGN.md`. Visual/DS/viewport audit stays with `mockup-reviewer` / skill `mockup-review`.
+
+## When to run
+
+- Standalone `/task` intent `ux-design` (report-only; profile `light`; steps only `task-analyst`; modes `synthesize` | `review`; `humanGates: []`).
+- Embedded: `feature` / `refactor` / `spike` / `spec-gen` on a UI stack when required-signal or advisory UI AC fires — inside the analyst step (no new pipeline agent). Required-signal: user asked UX, or AC require flows/states, or spec-gen page/feature.
+
+## Modes
+
+- `synthesize` — elicit IA, named primary flows, empty/error/loading matrix from the brief/AC.
+- `review` — critique a brief/wireframe/description **without** Figma. A `figma.com` URL with review-not-implement language is intent `mockup-review`, not this skill.
+
+## Order
+
+UX synthesis **before** skill `spec-authoring` / author mode when both apply. Analyst remains the only INDEX writer. Map headings via the rule's Spec feed table; do not paste the whole UX file into `docs/specs`.
+
+## Forbidden Figma MCP
+
+Do not call `get_metadata`, `get_design_context`, `get_screenshot`, `search_design_system`, `get_variable_defs`, `use_figma`, `create_new_file`, `generate_*`. Only `mockup-reviewer` reads Figma.
+
+## Load the checklist
+
+Load requestable rule `ux-design` and follow its required-signal vs advisory rules, forbidden MCP list, verdicts, surface-closure, and report headings.
+
+## Output
+
+Write `.cursor/team/tasks/<slug>/ux-design.md` and append that path to the **`analysis`** manifest entry (`authoritativePaths` / `evidencePaths`). Do **not** create a new producer row. Receipt stays on `analysis`: required `INCOMPLETE` (missing primary flows or empty/error/loading matrix) → DoR not met; advisory `INCOMPLETE` → notes only. Never copy the mockup FAIL-only hook.

package/presets/cursor/svelte/team/README.md

@@ -27,6 +27,7 @@ Artifact directory for the Cursor “agent team” pipeline.
       unit-test-plan.md
       documentation.md
       review.md
+      .memlog.md             # append-only agent notes (optional)
 ```
 
 ## pipeline.json schema
@@ -35,6 +36,7 @@ Artifact directory for the Cursor “agent team” pipeline.
 {
   "slug": "order-history-date-filter",
   "intent": "feature",
+  "specMode": "consume",
   "summary": "Add date filter to Order History",
   "steps": [
     { "agent": "task-analyst", "label": "Clarify and decompose" },
@@ -59,6 +61,8 @@ Artifact directory for the Cursor “agent team” pipeline.
 | `skipIf` | `debugger.fixed` \| `ci-investigator.resolved` |
 | `parallel` | Invoke all `agent` values in one parent turn |
 
+Optional top-level **`specMode`:** `consume` | `generate` | `none` (router echo; `brief.md` `## Spec mode` wins).
+
 ## status.json (pipeline mode)
 
 ```json
@@ -112,6 +116,13 @@ Bootstrap `<slug>/` by **writing** `pipeline.json` (Write tool). Runtime/hook ow
 
 Commit task artifacts if you want them to survive `ai-rules clean cursor`. Or copy finished tasks to `docs/agent-workflow/tasks/<slug>/`.
 
+
+## specMode, applyReadiness, memlog
+
+- **`specMode`:** `consume` | `generate` | `none` — primary in `brief.md` `## Spec mode`; optional top-level `pipeline.json` `specMode`. `none` skips INDEX/author mode (spike/research).
+- **`applyReadiness`:** YAML frontmatter on developer `implementation.md`; JSON-shaped `{ "state": "blocked"|"ready"|"all_done", "contextFiles": [] }` on the analyst receipt (analyst may emit `blocked` pre-gate). See `agent-artifact-contracts`.
+- **Memlog:** `.cursor/team/tasks/<slug>/.memlog.md` (Claude: `.claude/team/tasks/<slug>/.memlog.md`) — append-only, agent-written; `/task-continue` may read. Hook does not parse it. Example: `fixtures/memlog.example.md`.
+
 ## Artifact manifest and receipts
 
 Each slug stores one context index at `.cursor/team/tasks/<slug>/artifact-manifest.json`. Schema v1 is defined by shared core `agent-team/agent-artifact-contracts.md`: every entry declares its producer, status, authoritative paths, acceptance-criteria IDs, decomposition task IDs, timestamps, and a terminal completion receipt.

package/presets/cursor/svelte/team/fixtures/artifact-manifest.example.json

@@ -25,7 +25,7 @@
       "id": "analysis",
       "producer": "task-analyst",
       "status": "completed",
-      "authoritativePaths": ["brief.md", "decomposition.md"],
+      "authoritativePaths": ["brief.md", "decomposition.md", "ux-design.md"],
       "acceptanceCriteriaIds": ["AC-1", "AC-2"],
       "taskIds": ["T1", "T2"],
       "timestamps": {
@@ -36,7 +36,7 @@
       "receipt": {
         "outcome": "completed",
         "summary": "The acceptance criteria and implementation tasks are ready.",
-        "evidencePaths": ["brief.md", "decomposition.md"]
+        "evidencePaths": ["brief.md", "decomposition.md", "ux-design.md"]
       }
     },
     {
@@ -56,6 +56,24 @@
         "summary": "Implementation and focused unit coverage are complete.",
         "evidencePaths": ["implementation.md"]
       }
+    },
+    {
+      "id": "mockup-review",
+      "producer": "mockup-reviewer",
+      "status": "completed",
+      "authoritativePaths": ["mockup-review.md"],
+      "acceptanceCriteriaIds": ["AC-4", "AC-5", "AC-6", "AC-7", "AC-8"],
+      "taskIds": [],
+      "timestamps": {
+        "createdAt": "2026-07-31T12:05:30.000Z",
+        "updatedAt": "2026-07-31T12:05:45.000Z",
+        "completedAt": "2026-07-31T12:05:45.000Z"
+      },
+      "receipt": {
+        "outcome": "completed",
+        "summary": "Mockup review completed with verdict PASS_WITH_NOTES.",
+        "evidencePaths": ["mockup-review.md"]
+      }
     }
   ]
 }

package/presets/cursor/svelte/team/fixtures/feature-full.json

@@ -1,10 +1,15 @@
 {
   "slug": "example-feature-full",
   "intent": "feature",
+  "specMode": "consume",
   "profile": "full",
   "routingDecision": {
     "complexity": "high",
-    "riskFlags": ["cross-layer", "public-contract", "broad-test-surface"],
+    "riskFlags": [
+      "cross-layer",
+      "public-contract",
+      "broad-test-surface"
+    ],
     "routingReasons": [
       "The feature spans UI, state, and API boundaries, so architecture and implementation checkpoints are required.",
       "The public contract and e2e acceptance surface require independent validation and review."
@@ -14,15 +19,44 @@
   },
   "summary": "Multi-layer feature with e2e coverage",
   "steps": [
-    { "agent": "task-analyst", "label": "Clarify and decompose" },
-    { "agent": "solution-architect", "label": "Design boundaries", "model": "strong" },
-    { "agent": "feature-developer", "label": "Implement + unit tests", "scope": "unit-in-dev" },
-    { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
-    { "agent": "security-reviewer", "label": "Security review", "model": "strong" },
-    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" },
-    { "agent": "qa-tester", "label": "E2E", "scope": "e2e-only" }
+    {
+      "agent": "task-analyst",
+      "label": "Clarify and decompose"
+    },
+    {
+      "agent": "solution-architect",
+      "label": "Design boundaries",
+      "model": "strong"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Implement + unit tests",
+      "scope": "unit-in-dev"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "Validation gate",
+      "model": "cheap"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Security review",
+      "model": "strong"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review",
+      "model": "cheap"
+    },
+    {
+      "agent": "qa-tester",
+      "label": "E2E",
+      "scope": "e2e-only"
+    }
+  ],
+  "humanGates": [
+    "after:task-analyst"
   ],
-  "humanGates": ["after:task-analyst"],
   "autoChain": true,
   "skipped": []
 }

package/presets/cursor/svelte/team/fixtures/feature-with-figma-url.json

@@ -0,0 +1,17 @@
+{
+  "slug": "example-feature-with-figma",
+  "intent": "feature",
+  "profile": "full",
+  "summary": "Feature with Figma mockup URL — mockup-reviewer after analyst, before architect and developer",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify and decompose" },
+    { "agent": "mockup-reviewer", "label": "Figma mockup review", "model": "strong" },
+    { "agent": "solution-architect", "label": "Design boundaries", "model": "strong" },
+    { "agent": "feature-developer", "label": "Implement" },
+    { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
+    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": []
+}

package/presets/cursor/svelte/team/fixtures/feature-with-ux-no-figma.json

@@ -0,0 +1,17 @@
+{
+  "slug": "example-feature-with-ux-no-figma",
+  "intent": "feature",
+  "profile": "standard",
+  "summary": "Feature with required-signal UX and no Figma URL — task-analyst loads skill ux-design; no mockup-reviewer step",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify, UX design, decompose" },
+    { "agent": "feature-developer", "label": "Implement" },
+    { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
+    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "mockup-reviewer", "reason": "No figma.com URL; analyst skill ux-design covers behavioral UX" }
+  ]
+}

package/presets/cursor/svelte/team/fixtures/memlog.example.md

@@ -0,0 +1,9 @@
+# Memlog example
+
+Append-only. Agents write; `/task-continue` may read. The hook does not parse this file.
+
+## 2026-08-13
+
+- `decision`: specMode=generate; research-before-spec requested
+- `claim`: empty-cart copy lives in CartEmpty.tsx (code-archaeology, inferred)
+- `assumption`: no guest checkout in v1

package/presets/cursor/svelte/team/fixtures/mockup-review-fail-embedded-status.json

@@ -0,0 +1,8 @@
+{
+  "slug": "example-mockup-fail-gate",
+  "state": "awaiting_approval",
+  "currentAgent": "mockup-reviewer",
+  "awaitingHumanGate": true,
+  "retryAfterFix": null,
+  "note": "Embedded mockup FAIL: hook must NOT set retryAfterFix to feature-developer. Resume only via /task-continue."
+}

package/presets/cursor/svelte/team/fixtures/mockup-review-standalone.json

@@ -0,0 +1,14 @@
+{
+  "slug": "example-mockup-review-standalone",
+  "intent": "mockup-review",
+  "profile": "light",
+  "summary": "Standalone Figma mockup review (report-only)",
+  "steps": [
+    { "agent": "mockup-reviewer", "label": "Figma mockup review", "model": "strong" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "feature-developer", "reason": "Standalone mockup-review is report-only" }
+  ]
+}

package/presets/cursor/svelte/team/fixtures/ux-design-standalone.json

@@ -0,0 +1,15 @@
+{
+  "slug": "example-ux-design-standalone",
+  "intent": "ux-design",
+  "profile": "light",
+  "summary": "Standalone behavioral UX design (analyst + skill ux-design; report-only; no developer)",
+  "steps": [
+    { "agent": "task-analyst", "label": "UX design (skill ux-design)" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "feature-developer", "reason": "Standalone ux-design is report-only" },
+    { "agent": "mockup-reviewer", "reason": "No figma.com URL; not a mockup review" }
+  ]
+}

package/scripts/aggregate-agent-task-metrics.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const args = process.argv.slice(2);
+const teamRootIndex = args.indexOf('--team-root');
+const teamRoot =
+  teamRootIndex >= 0
+    ? path.resolve(args[teamRootIndex + 1] ?? '')
+    : path.join(process.cwd(), '.cursor', 'team');
+const tasksDir = path.join(teamRoot, 'tasks');
+const incomplete = [];
+const attempts = [];
+const tasks = [];
+const gateWaits = [];
+const attributionConfidenceCounts = new Map();
+let unmatchedAttemptCount = 0;
+let duplicateTerminalAttemptCount = 0;
+let duplicateAttemptIdCount = 0;
+let missingLedgerCount = 0;
+let malformedLedgerCount = 0;
+let invalidLedgerCount = 0;
+let unterminatedAttemptCount = 0;
+
+function readMetrics(filePath) {
+  if (!fs.existsSync(filePath)) {
+    incomplete.push({ file: filePath, category: 'missing_ledger', reason: 'missing ledger' });
+    missingLedgerCount += 1;
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    incomplete.push({ file: filePath, category: 'malformed_json', reason: 'malformed JSON' });
+    malformedLedgerCount += 1;
+    return;
+  }
+  if (parsed.schemaVersion !== 1 || !parsed.task || !Array.isArray(parsed.events)) {
+    incomplete.push({ file: filePath, category: 'unsupported_schema', reason: 'unsupported schema' });
+    return;
+  }
+  try {
+    collect(parsed, filePath);
+  } catch (error) {
+    incomplete.push({
+      file: filePath,
+      category: 'invalid_ledger',
+      reason: error instanceof Error ? error.message : 'invalid ledger structure',
+    });
+    invalidLedgerCount += 1;
+  }
+}
+
+function collect(metrics, filePath) {
+  const starts = new Map();
+  const gateStarts = new Map();
+  const terminalAttempts = new Set();
+  let taskCompleted = false;
+  let ledgerIncomplete = false;
+
+  for (const event of metrics.events) {
+    if (event.type === 'attempt_started' && event.attemptId) {
+      if (starts.has(event.attemptId)) {
+        incomplete.push({
+          file: filePath,
+          category: 'duplicate_attempt_id',
+          reason: `duplicate attempt ID ${event.attemptId}`,
+        });
+        duplicateAttemptIdCount += 1;
+        ledgerIncomplete = true;
+        continue;
+      }
+      starts.set(event.attemptId, event);
+    }
+    if (event.type === 'attempt_finished' && event.attemptId) {
+      const start = starts.get(event.attemptId);
+      if (!start) {
+        incomplete.push({
+          file: filePath,
+          category: 'unmatched_attempt',
+          reason: `unmatched attempt ${event.attemptId}`,
+        });
+        unmatchedAttemptCount += 1;
+        ledgerIncomplete = true;
+        continue;
+      }
+      if (terminalAttempts.has(event.attemptId)) {
+        incomplete.push({
+          file: filePath,
+          category: 'duplicate_terminal_attempt',
+          reason: `duplicate terminal attempt ${event.attemptId}`,
+        });
+        duplicateTerminalAttemptCount += 1;
+        ledgerIncomplete = true;
+        continue;
+      }
+      terminalAttempts.add(event.attemptId);
+      const attributionConfidence = event.attributionConfidence ?? 'unknown';
+      attributionConfidenceCounts.set(
+        attributionConfidence,
+        (attributionConfidenceCounts.get(attributionConfidence) ?? 0) + 1,
+      );
+      attempts.push({
+        ...metrics.task,
+        agent: start.agent ?? 'unknown',
+        role: start.role ?? 'unknown',
+        durationMs: Number.isFinite(event.durationMs) ? event.durationMs : null,
+        outcome: event.outcome ?? 'unknown',
+        attributionConfidence,
+      });
+    }
+    if (event.type === 'human_gate_started' && event.eventId) {
+      gateStarts.set(event.eventId, event);
+    }
+    if (event.type === 'human_gate_ended') {
+      const start = event.gateStartedEventId ? gateStarts.get(event.gateStartedEventId) : undefined;
+      const elapsed = start ? Date.parse(event.at) - Date.parse(start.at) : NaN;
+      if (Number.isFinite(elapsed) && elapsed >= 0) gateWaits.push(elapsed);
+    }
+    if (event.type === 'task_completed') taskCompleted = true;
+  }
+
+  for (const attemptId of starts.keys()) {
+    if (terminalAttempts.has(attemptId)) continue;
+    incomplete.push({
+      file: filePath,
+      category: 'unterminated_attempt',
+      reason: `unterminated attempt ${attemptId}`,
+    });
+    unterminatedAttemptCount += 1;
+    ledgerIncomplete = true;
+  }
+
+  if (taskCompleted && !ledgerIncomplete) tasks.push(metrics.task);
+}
+
+function groupBy(items, keyFor) {
+  const groups = new Map();
+  for (const item of items) {
+    const key = keyFor(item);
+    groups.set(key, [...(groups.get(key) ?? []), item]);
+  }
+  return [...groups.values()];
+}
+
+if (!fs.existsSync(tasksDir)) {
+  console.error(`Task directory does not exist: ${tasksDir}`);
+  process.exit(1);
+}
+
+for (const entry of fs.readdirSync(tasksDir, { withFileTypes: true })) {
+  if (entry.isDirectory()) readMetrics(path.join(tasksDir, entry.name, 'metrics.json'));
+}
+
+const byAgentRole = groupBy(
+  attempts,
+  (item) => `${item.platform}|${item.stack}|${item.preset}|${item.agent}|${item.role}`,
+).map((group) => {
+  const sample = group[0];
+  const durations = group.map((item) => item.durationMs).filter((value) => value !== null);
+  const sumDurationMs = durations.reduce((sum, value) => sum + value, 0);
+  return {
+    platform: sample.platform,
+    stack: sample.stack,
+    preset: sample.preset,
+    agent: sample.agent,
+    role: sample.role,
+    count: group.length,
+    completedCount: group.filter((item) => item.outcome === 'completed').length,
+    sumDurationMs,
+    avgDurationMs: durations.length ? sumDurationMs / durations.length : null,
+  };
+});
+
+const taskCountsByRunId = [...new Map(tasks.map((task) => [task.runId, task])).values()].map((task) => ({
+  runId: task.runId,
+  slug: task.slug,
+  platform: task.platform,
+  stack: task.stack,
+  preset: task.preset,
+  intent: task.intent,
+}));
+
+process.stdout.write(
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      teamRoot,
+      agentRole: byAgentRole,
+      taskCountsByRunId,
+      humanGateWait: {
+        count: gateWaits.length,
+        sumDurationMs: gateWaits.reduce((sum, value) => sum + value, 0),
+      },
+      attributionConfidence: Object.fromEntries(attributionConfidenceCounts),
+      completeness: {
+        missingLedgerCount,
+        malformedLedgerCount,
+        invalidLedgerCount,
+        duplicateAttemptIdCount,
+        unterminatedAttemptCount,
+        unmatchedAttemptCount,
+        duplicateTerminalAttemptCount,
+      },
+      incomplete,
+    },
+    null,
+    2,
+  )}\n`,
+);

package/scripts/check-hook-only-lifecycle.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# FAIL if agent/skill/command prompts still instruct writers to mutate status.json.
+# The orchestration hook is the sole lifecycle writer; agents upsert artifact-manifest receipts.
+# Exit 0 on OK; exit 1 on any FAIL.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+export AI_RULES_PRESETS_ROOT="$ROOT/packages/ai-rules/presets"
+
+python3 <<'PY'
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+presets = Path(os.environ["AI_RULES_PRESETS_ROOT"])
+# Imperative write instructions — not "do not mutate" / "runtime owns" / schema docs.
+FORBIDDEN = [
+    re.compile(r"Update `status\.json`:"),
+    re.compile(r"set `status\.json` to"),
+]
+
+hits: list[str] = []
+for path in presets.rglob("*"):
+    if path.suffix not in {".md", ".mdc"}:
+        continue
+    if "/hooks/" in path.as_posix():
+        continue
+    text = path.read_text(encoding="utf-8")
+    rel = path.relative_to(presets)
+    for i, line in enumerate(text.splitlines(), 1):
+        for pat in FORBIDDEN:
+            if pat.search(line):
+                hits.append(f"{rel}:{i}: {line.strip()}")
+
+if hits:
+    print(f"FAIL: {len(hits)} status.json write instruction(s) outside hooks:")
+    for h in hits:
+        print(f"  {h}")
+    sys.exit(1)
+
+print("OK: no agent/skill/command status.json write instructions")
+sys.exit(0)
+PY

package/scripts/check-preset-i18n.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Soft/hard Cyrillic audit for preset prose.
+# Soft (default): warn and exit 0. Hard: AI_RULES_I18N_FAIL=1 → exit 1 on unmarked Cyrillic.
+# Keep marker window: ±3 lines (matches docs/PRESET-ENGLISH-STYLE.md).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+PRESETS="$ROOT/packages/ai-rules/presets"
+SOFT="${AI_RULES_I18N_SOFT:-1}"
+FAIL="${AI_RULES_I18N_FAIL:-0}"
+
+python3 - "$PRESETS" "$SOFT" "$FAIL" <<'PY'
+from __future__ import annotations
+import re, sys
+from pathlib import Path
+
+presets = Path(sys.argv[1])
+soft = sys.argv[2] != "0"
+fail = sys.argv[3] == "1"
+cyr = re.compile(r"[\u0400-\u04FF]")
+keep = re.compile(r"<!--\s*i18n-keep:\s*(E4|E5|E7)(?:\s*[—\-].*?)?\s*-->")
+# Markdown/prose + hook scripts (comments) under presets
+SUFFIXES = {".md", ".mdc", ".sh", ".json", ".mjs", ".ts", ".js"}
+WINDOW = 3  # ±3 lines around a Cyrillic match
+
+violations = []
+kept = 0
+for path in presets.rglob("*"):
+    if path.suffix not in SUFFIXES:
+        continue
+    if "/team/tasks/" in str(path).replace("\\", "/"):
+        continue
+    try:
+        text = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        continue
+    if not cyr.search(text):
+        continue
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        if not cyr.search(line):
+            continue
+        lo = max(0, i - WINDOW)
+        hi = min(len(lines), i + WINDOW + 1)
+        if any(keep.search(lines[j]) for j in range(lo, hi)):
+            kept += 1
+            continue
+        violations.append(f"{path}:{i + 1}:{line[:120]}")
+
+print(f"Preset i18n audit: unmarked Cyrillic lines={len(violations)}; kept-marked≈{kept}")
+for v in violations[:50]:
+    print(f"  {v}")
+if len(violations) > 50:
+    print(f"  ... and {len(violations) - 50} more")
+
+if violations and (fail or not soft):
+    if fail:
+        sys.exit(1)
+print("Result:", "WARN (soft)" if violations else "OK")
+sys.exit(0)
+PY