@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/opencode/svelte/team/fixtures/metrics-scenarios/tasks/serial-retry/metrics.json

@@ -0,0 +1,124 @@
+{
+  "schemaVersion": 1,
+  "task": {
+    "runId": "serial-retry-run",
+    "slug": "serial-retry",
+    "preset": "ai-rules",
+    "stack": "svelte",
+    "platform": "cursor",
+    "intent": "feature",
+    "profile": "full"
+  },
+  "events": [
+    {
+      "eventId": "serial-retry-run:task",
+      "type": "task_started",
+      "at": "2026-07-31T14:00:00.000Z",
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:2:code-reviewer:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T14:00:00.000Z",
+      "attemptId": "serial-retry-run:step-2:code-reviewer:attempt-1",
+      "stepIndex": 2,
+      "stepLabel": null,
+      "agent": "code-reviewer",
+      "role": "review",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:2:code-reviewer:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T14:01:00.000Z",
+      "attemptId": "serial-retry-run:step-2:code-reviewer:attempt-1",
+      "outcome": "changes_requested",
+      "durationMs": 60000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:retry:1",
+      "type": "retry_scheduled",
+      "at": "2026-07-31T14:01:00.000Z",
+      "attemptId": "serial-retry-run:step-2:code-reviewer:attempt-1",
+      "nextAgent": "feature-developer",
+      "retryAfterFix": "code-reviewer",
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:1:feature-developer:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T14:01:00.000Z",
+      "attemptId": "serial-retry-run:step-1:feature-developer:attempt-1",
+      "stepIndex": 1,
+      "stepLabel": null,
+      "agent": "feature-developer",
+      "role": "implementation",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:1:feature-developer:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T14:03:00.000Z",
+      "attemptId": "serial-retry-run:step-1:feature-developer:attempt-1",
+      "outcome": "completed",
+      "durationMs": 120000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:retry:2",
+      "type": "retry_scheduled",
+      "at": "2026-07-31T14:03:00.000Z",
+      "attemptId": "serial-retry-run:step-1:feature-developer:attempt-1",
+      "nextAgent": "code-reviewer",
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:2:code-reviewer:2:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T14:03:00.000Z",
+      "attemptId": "serial-retry-run:step-2:code-reviewer:attempt-2",
+      "stepIndex": 2,
+      "stepLabel": null,
+      "agent": "code-reviewer",
+      "role": "review",
+      "attempt": 2,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:2:code-reviewer:2:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T14:04:00.000Z",
+      "attemptId": "serial-retry-run:step-2:code-reviewer:attempt-2",
+      "outcome": "completed",
+      "durationMs": 60000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "serial-retry-run:done",
+      "type": "task_completed",
+      "at": "2026-07-31T14:04:00.000Z",
+      "outcome": "completed",
+      "source": "hook",
+      "attributionConfidence": "high"
+    }
+  ]
+}

package/presets/opencode/svelte/team/fixtures/metrics-scenarios/tasks/validation-failed/metrics.json

@@ -0,0 +1,124 @@
+{
+  "schemaVersion": 1,
+  "task": {
+    "runId": "validation-failed-run",
+    "slug": "validation-failed",
+    "preset": "ai-rules",
+    "stack": "svelte",
+    "platform": "cursor",
+    "intent": "feature",
+    "profile": "full"
+  },
+  "events": [
+    {
+      "eventId": "validation-failed-run:task",
+      "type": "task_started",
+      "at": "2026-07-31T15:00:00.000Z",
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T15:00:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-1",
+      "stepIndex": 2,
+      "stepLabel": null,
+      "agent": "build-verifier",
+      "role": "validation",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T15:02:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-1",
+      "outcome": "validation_failed",
+      "durationMs": 120000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:retry:1",
+      "type": "retry_scheduled",
+      "at": "2026-07-31T15:02:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-1",
+      "nextAgent": "feature-developer",
+      "retryAfterFix": "build-verifier",
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:1:feature-developer:1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T15:02:00.000Z",
+      "attemptId": "validation-failed-run:step-1:feature-developer:attempt-1",
+      "stepIndex": 1,
+      "stepLabel": null,
+      "agent": "feature-developer",
+      "role": "implementation",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:1:feature-developer:1:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T15:05:00.000Z",
+      "attemptId": "validation-failed-run:step-1:feature-developer:attempt-1",
+      "outcome": "completed",
+      "durationMs": 180000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:retry:2",
+      "type": "retry_scheduled",
+      "at": "2026-07-31T15:05:00.000Z",
+      "attemptId": "validation-failed-run:step-1:feature-developer:attempt-1",
+      "nextAgent": "build-verifier",
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:2:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T15:05:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-2",
+      "stepIndex": 2,
+      "stepLabel": null,
+      "agent": "build-verifier",
+      "role": "validation",
+      "attempt": 2,
+      "parallelGroupId": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:2:build-verifier:2:finish",
+      "type": "attempt_finished",
+      "at": "2026-07-31T15:06:00.000Z",
+      "attemptId": "validation-failed-run:step-2:build-verifier:attempt-2",
+      "outcome": "completed",
+      "durationMs": 60000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "validation-failed-run:done",
+      "type": "task_completed",
+      "at": "2026-07-31T15:06:00.000Z",
+      "outcome": "completed",
+      "source": "hook",
+      "attributionConfidence": "high"
+    }
+  ]
+}

package/presets/opencode/svelte/team/fixtures/metrics.example.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": 1,
+  "task": {
+    "runId": "example-run-1",
+    "slug": "example-feature-full",
+    "preset": "ai-rules",
+    "stack": "svelte",
+    "platform": "cursor",
+    "intent": "feature",
+    "profile": "full"
+  },
+  "events": [
+    {
+      "eventId": "example-run-1:task_started",
+      "type": "task_started",
+      "at": "2026-07-31T14:00:00.000Z",
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "example-run-1:attempt-1:start",
+      "type": "attempt_started",
+      "at": "2026-07-31T14:00:00.000Z",
+      "attemptId": "example-run-1:step-0:task-analyst:attempt-1",
+      "stepIndex": 0,
+      "stepLabel": "Clarify and decompose",
+      "agent": "task-analyst",
+      "role": "planning",
+      "attempt": 1,
+      "parallelGroupId": null,
+      "source": "router",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "example-run-1:attempt-1:end",
+      "type": "attempt_finished",
+      "at": "2026-07-31T14:02:00.000Z",
+      "attemptId": "example-run-1:step-0:task-analyst:attempt-1",
+      "outcome": "completed",
+      "durationMs": 120000,
+      "retryAfterFix": null,
+      "source": "hook",
+      "attributionConfidence": "high"
+    },
+    {
+      "eventId": "example-run-1:task_completed",
+      "type": "task_completed",
+      "at": "2026-07-31T14:02:00.000Z",
+      "outcome": "completed",
+      "source": "hook",
+      "attributionConfidence": "high"
+    }
+  ]
+}

package/presets/opencode/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/opencode/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/opencode/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

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 /**
- * Aggregate `metrics.json` ledgers across `.cursor/team/tasks/*` and emit a JSON report.
+ * Aggregate `metrics.json` ledgers across `.ai.local/team/tasks/*` and emit a JSON report.
  *
  * Usage:
  *   node scripts/aggregate-agent-task-metrics.mjs [--team-root <dir>] [--help]
  *
- * Defaults to `<cwd>/.cursor/team` when --team-root is omitted.
+ * Defaults to `<cwd>/.ai.local/team` when --team-root is omitted.
  */
 
 import fs from 'node:fs';
@@ -21,7 +21,7 @@ Usage:
 
 Options:
   --team-root <dir>  Directory containing a 'tasks/' subfolder with *.metrics.json ledgers
-                     (default: <cwd>/.cursor/team)
+                     (default: <cwd>/.ai.local/team)
 
 Output: JSON report on stdout (machine-readable).`);
   process.exit(0);
@@ -31,7 +31,7 @@ const teamRootIndex = args.indexOf('--team-root');
 const teamRoot =
   teamRootIndex >= 0
     ? path.resolve(args[teamRootIndex + 1] ?? '')
-    : path.join(process.cwd(), '.cursor', 'team');
+    : path.join(process.cwd(), '.ai.local', 'team');
 const tasksDir = path.join(teamRoot, 'tasks');
 const incomplete = [];
 const attempts = [];

package/scripts/capture-cli-golden.mjs

@@ -28,11 +28,14 @@ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), `ai-rules-golden-${tool}-`));
 try {
   runInit(cli, tmp, tool, preset);
   const files = snapshotInstall(tmp);
-  if (tool === 'mavis') {
-    delete files['.mavis/.ai-rules-install.json'];
-  }
-  if (tool === 'opencode') {
-    delete files['.opencode/.ai-rules-install.json'];
+  const manifestKey = {
+    cursor: '.cursor/.ai-rules-install.json',
+    claude: '.claude/.ai-rules-install.json',
+    mavis: '.mavis/.ai-rules-install.json',
+    opencode: '.opencode/.ai-rules-install.json',
+  }[tool];
+  if (manifestKey) {
+    delete files[manifestKey];
   }
   const golden = goldenDocument({
     tool,

package/scripts/check-chain-hook-coverage.sh

@@ -17,6 +17,7 @@ export AI_RULES_PRESETS_ROOT="$ROOT/packages/ai-rules/presets"
 python3 <<'PY'
 from __future__ import annotations
 
+import json
 import os
 import re
 import sys
@@ -45,10 +46,22 @@ STACKS_WITH_OPENSPEC = {
     ("claude", "php-hexagonal"),
     ("claude", "php-laravel"),
     ("claude", "svelte"),
-    ("mavis", "next"),
-    ("opencode", "next"),
 }
 
+
+def released_contract_stacks(platform: str) -> list[str]:
+    contract = presets / platform / "platform-contract.json"
+    if not contract.is_file():
+        return []
+    data = json.loads(contract.read_text(encoding="utf-8"))
+    stacks = data.get("releasedStacks") or []
+    return [stack for stack in stacks if stack != "mcp-ts"]
+
+
+for platform in ("mavis", "opencode"):
+    for stack in released_contract_stacks(platform):
+        STACKS_WITH_OPENSPEC.add((platform, stack))
+
 # Agents used only outside the pipeline (no chain hook entry expected).
 PIPELINE_EXEMPT = {"task-router", "codebase-analyzer"}
 

package/scripts/check-frontmatter.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Frontmatter validity gate (dependency-free heuristic).
+ *
+ * Flags the YAML failure modes that shipped silently before: unquoted scalars
+ * containing `: ` / ` #`, and unquoted list items starting with a YAML-special
+ * character (`*`, `&`, `!`, `{`, `[`, `|`, `>`, `@`, `%`, backtick). Also flags
+ * tab indentation. Exit 1 on any finding.
+ *
+ * Full YAML parsing is intentionally avoided: the published package has zero
+ * runtime dependencies and the structure workflow does not install dev deps.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const packageDirectory = path.resolve(scriptDirectory, '..');
+const presetsRoot = path.join(packageDirectory, 'presets');
+
+const SCALAR_KEYS = /^([A-Za-z0-9_-]+):[ \t]*(.*)$/;
+const LIST_ITEM = /^([ \t]*-[ \t]+)(.*)$/;
+const SAFE_SCALAR = /^(['"]).*\1$|^(true|false|null|~)$|^-?\d+(\.\d+)?$|^[|>][-+]?$|^\[\]$|^\{\}$/;
+const SPECIAL_LEAD = /^[*&!%@`]/;
+
+const problems = [];
+
+function checkLine(file, lineNumber, line) {
+  if (/^\t|^[ \t]*\t/.test(line)) {
+    problems.push(`${file}:${lineNumber}: tab indentation is not valid YAML`);
+    return;
+  }
+  const kv = line.match(SCALAR_KEYS);
+  if (kv && kv[2] !== '' && !SAFE_SCALAR.test(kv[2])) {
+    const value = kv[2];
+    if (/: /.test(value) || /:[ \t]*$/.test(value) || /\s#/.test(value) || SPECIAL_LEAD.test(value)) {
+      problems.push(
+        `${file}:${lineNumber}: unquoted YAML value needs quoting: ${line.trim()}`,
+      );
+    }
+    return;
+  }
+  const item = line.match(LIST_ITEM);
+  if (item && !SAFE_SCALAR.test(item[2]) && SPECIAL_LEAD.test(item[2])) {
+    problems.push(`${file}:${lineNumber}: unquoted YAML list item needs quoting: ${line.trim()}`);
+  }
+}
+
+function walk(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full);
+    } else if (/\.(md|mdc)$/.test(entry.name)) {
+      const text = fs.readFileSync(full, 'utf8');
+      if (!text.startsWith('---\n')) {
+        continue;
+      }
+      const end = text.indexOf('\n---\n', 4);
+      if (end < 0) {
+        continue;
+      }
+      const frontmatter = text.slice(4, end);
+      const rel = path.relative(packageDirectory, full);
+      frontmatter.split('\n').forEach((line, index) => checkLine(rel, index + 2, line));
+    }
+  }
+}
+
+walk(presetsRoot);
+
+if (problems.length > 0) {
+  console.error(`Frontmatter check: ${problems.length} problem(s)`);
+  for (const problem of problems.slice(0, 50)) {
+    console.error(`  ${problem}`);
+  }
+  if (problems.length > 50) {
+    console.error(`  ... and ${problems.length - 50} more`);
+  }
+  process.exit(1);
+}
+
+console.log('Frontmatter check: OK');

package/scripts/check-generated-drift.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * Generated-tree drift gate.
+ *
+ * Regenerates `presets/mavis/<stack>` and `presets/opencode/<stack>` from the
+ * Cursor sources into a temp root and byte-compares them with the committed
+ * trees. Catches two classes of drift that the adapter-map checks cannot:
+ *   - hand-edits to a generated file;
+ *   - generator logic changes that were not followed by a regeneration.
+ *
+ * Exit 1 on any drift; prints the offending paths.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { generateMavisStack } from './lib/generate-mavis-adapter.mjs';
+import { generateOpencodeStack } from './lib/generate-opencode-adapter.mjs';
+import { loadReleasedStacks } from './lib/generate-adapter-common.mjs';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const packageDirectory = path.resolve(scriptDirectory, '..');
+const presetsRoot = path.join(packageDirectory, 'presets');
+
+function walkRelative(root) {
+  const out = [];
+  const visit = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(full);
+      } else if (entry.isFile()) {
+        out.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  };
+  if (fs.existsSync(root)) {
+    visit(root);
+  }
+  return out.sort();
+}
+
+function sha256File(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
+function compareTrees(expectedRoot, actualRoot, label, drift) {
+  const expected = walkRelative(expectedRoot);
+  const actual = walkRelative(actualRoot);
+  const expectedSet = new Set(expected);
+  const actualSet = new Set(actual);
+  for (const rel of expected) {
+    if (!actualSet.has(rel)) {
+      drift.push(`${label}: committed file missing from generator output: ${rel}`);
+    } else if (sha256File(path.join(expectedRoot, rel)) !== sha256File(path.join(actualRoot, rel))) {
+      drift.push(`${label}: content drift in ${rel}`);
+    }
+  }
+  for (const rel of actual) {
+    if (!expectedSet.has(rel)) {
+      drift.push(`${label}: generator output has an uncommitted file: ${rel}`);
+    }
+  }
+}
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ai-rules-generated-drift-'));
+const drift = [];
+try {
+  fs.mkdirSync(path.join(tempRoot, 'presets'), { recursive: true });
+  fs.cpSync(path.join(presetsRoot, 'cursor'), path.join(tempRoot, 'presets', 'cursor'), {
+    recursive: true,
+  });
+  fs.cpSync(path.join(presetsRoot, '_shared'), path.join(tempRoot, 'presets', '_shared'), {
+    recursive: true,
+  });
+
+  for (const [platform, generate] of [
+    ['mavis', generateMavisStack],
+    ['opencode', generateOpencodeStack],
+  ]) {
+    const stacks = loadReleasedStacks(presetsRoot, platform);
+    for (const stack of stacks) {
+      generate(stack, { root: tempRoot });
+      compareTrees(
+        path.join(presetsRoot, platform, stack),
+        path.join(tempRoot, 'presets', platform, stack),
+        `${platform}/${stack}`,
+        drift,
+      );
+    }
+  }
+} finally {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}
+
+if (drift.length > 0) {
+  console.error(`Generated-tree drift detected (${drift.length} issue(s)):`);
+  for (const line of drift) {
+    console.error(`  ${line}`);
+  }
+  console.error('Run: node scripts/generate-mavis.mjs --stack <stack> and generate-opencode.mjs --stack <stack>');
+  process.exit(1);
+}
+
+console.log('Generated-tree drift check: OK (mavis + opencode match generator output)');