@bonesofspring/ai-rules 0.2.18 → 0.2.19

package/presets/cursor/svelte/skills/feature-delivery/SKILL.md

@@ -20,7 +20,15 @@ Implement only the current AC / decomposition task. Clarify ambiguity before cod
 
 ## Handoff
 
-Summarize by layer, validation results, and known gaps. Agent team: update `.cursor/team/tasks/<slug>/status.json`.
+Summarize by layer, validation results, and known gaps. Agent team: upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools MCP for live-app debug and performance (app must be running). Storybook MCP if present and the work is component docs/stories.
+
 
 ## Design guidance
 

package/presets/cursor/svelte/skills/spec-discovery/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: spec-discovery
+description: Opt-in research-before-spec for task-analyst author mode. 11 named methods plus a mandatory claim ledger. Use when the user or AC asks discovery before generating docs/specs — not default /task consume.
+---
+
+# Spec discovery
+
+Requestable — **not** always-on. Load **only** in **task-analyst author mode** when the user or AC asks research-before-spec (including `/spec-start` with that intent). Never default consume `/task`. Not a pipeline step.
+
+Load **`product-specs`** (and **`product-specs-authoring`** after this skill if authoring follows). Do **not** invent product behavior. Do **not** create a second spec-file tree.
+
+## Load policy
+
+1. Pick a **subset** of methods that fit the task — not all 11 every time.
+2. **`claim-ledger` is mandatory** whenever this skill runs.
+3. Write chronological notes to `.cursor/team/tasks/<slug>/.memlog.md` (append-only). Do **not** mutate `status.json` / `metrics.json`.
+4. Discovery output lives in memlog + `brief.md` sections. Then hand off to skill **`spec-authoring`** (or stop if `specMode: none`).
+
+Backend / MCP stacks: skip UI-only examples; prefer `analog-scan`, `code-archaeology`, `problem-define`, `assumption-audit`, `claim-ledger`.
+
+## Methods
+
+| Method | Produces | Skip when |
+|--------|----------|-----------|
+| **intake-capture** | Raw idea, origin, first unknowns → memlog + brief Research inputs | User prompt + AC already complete |
+| **index-locator** | Related INDEX rows + linked spec paths + gaps | `specMode: none` or INDEX absent without consume intent |
+| **code-archaeology** | Observed behavior labeled `inferred`/`draft` with path citations | Greenfield with no relevant code |
+| **research-pack-scan** | Claims from `team/tasks/<slug>/research/**` or user-supplied paths | No research paths cited |
+| **evidence-against** | Reasons the idea may fail | Internal spike with no product/external risk |
+| **problem-define** | Who hurts, goals, non-goals, cost of inaction → brief | Brief Goal + Out of scope already exhaustive |
+| **concept-shape** | 2–3 approach options + appetite (small/medium/large); no API design | `architecture.md` exists or one obvious path |
+| **working-backwards-check** | Headline + 5 customer objections + verdict `forged` / `needs-heat` / `cracked` | Consume mode with approved specs |
+| **assumption-audit** | Assumption register → brief Assumptions + `open_questions` | Never skip in author mode (keep lightweight) |
+| **analog-scan** | 2–3 repo analogs via `reference-features` / code search | No plausible analog |
+| **claim-ledger** | Markdown table `source → claim` for every product-behavior claim | **Never skip** when this skill is loaded |
+
+## Claim ledger (required)
+
+Block spec authoring until every product-behavior claim has a source:
+
+```markdown
+| Source | Claim |
+|--------|-------|
+| brief AC-3 | Checkout shows empty cart copy |
+| code-archaeology inferred | Empty state uses an illustration |
+```
+
+Sources: AC / user / UI copy / labeled code inference / research path. Unsourced claims → `open_questions`.
+
+## Memlog
+
+Path: `.cursor/team/tasks/<slug>/.memlog.md`. Chronological `## YYYY-MM-DD` headings. Optional tags: `decision`, `assumption`, `override`, `event`, `claim`.
+
+## Forbidden
+
+- 108-technique catalogs, HTML composers, party-mode, five `assess.*` slash commands, Python memlog runtime.
+- Dummy INDEX rows when `specMode: none`.
+- Dumping the whole `docs/specs/**` tree — locator is INDEX → linked page + optional `feature.md`.

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/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/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/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