bigpowers 2.88.17 → 2.89.0

package/scripts/lib/migrate-version-common.sh

@@ -21,23 +21,32 @@ EOF
 }
 
 migrate_installed_version() {
-  node -e "console.log(require('$BIGPOWERS_ROOT/package.json').version)" 2>/dev/null || echo "unknown"
+  node -e 'console.log(require(process.argv[1]).version)' "$BIGPOWERS_ROOT/package.json" 2>/dev/null || echo "unknown"
+}
+
+migrate_validate_version() {
+  local version="$1" label="$2"
+  local pattern='^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$'
+  if [[ ! "$version" =~ $pattern ]]; then
+    echo "migrate-version: invalid $label version; expected major.minor.patch with optional prerelease/build metadata" >&2
+    return 4
+  fi
 }
 
 migrate_yaml_get() {
   local file="$1" key="$2"
-  $PYTHON -c "
+  "$PYTHON" -c "
 import yaml, sys
 try:
-    d = yaml.safe_load(open('$file'))
+    d = yaml.safe_load(open(sys.argv[1]))
     val = d
-    for k in '$key'.split('.'):
+    for k in sys.argv[2].split('.'):
         if not isinstance(val, dict): sys.exit(1)
         val = val.get(k)
     if val is None: sys.exit(1)
     print(val)
 except: sys.exit(1)
-" 2>/dev/null
+" "$file" "$key" 2>/dev/null
 }
 
 log_info()  { echo "  [INFO] $*"; }
@@ -111,3 +120,4 @@ migrate_detect_version() {
   fi
   return 0
 }
+

package/scripts/lib/migrate-version-plan.sh

@@ -8,15 +8,14 @@ MIGRATE_VERSION_PLAN_LOADED=1
 migrate_build_plan() {
   echo "migrate-version: building migration plan from $REGISTRY …"
 
-  MIGRATION_PLAN="$($PYTHON -c "
+  MIGRATION_PLAN="$("$PYTHON" -c "
 import yaml, json, sys
 
-with open('$REGISTRY') as f:
+with open(sys.argv[1]) as f:
     parts = f.read().split('---')
     fm = yaml.safe_load(parts[1])
 
-detected = '$DETECTED'
-installed = '$INSTALLED'
+detected, installed = sys.argv[2:4]
 
 plan = []
 for m in sorted(fm.get('migrations', []), key=lambda x: x.get('order', 99)):
@@ -30,7 +29,7 @@ for m in sorted(fm.get('migrations', []), key=lambda x: x.get('order', 99)):
 
 applicable = [m for m in plan if m['since_version'] > detected and m['since_version'] <= installed]
 print(json.dumps(applicable))
-" 2>/dev/null)"
+" "$REGISTRY" "$DETECTED" "$INSTALLED")"
 
   MIGRATION_COUNT="$(echo "$MIGRATION_PLAN" | $PYTHON -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null)"
 
@@ -79,7 +78,7 @@ for m in json.load(sys.stdin):
   echo "$MIGRATION_PLAN" | $PYTHON -c "
 import json, sys, os
 for m in json.load(sys.stdin):
-    bundle_path = os.path.join('$MIGRATIONS_DIR', m['file'])
+    bundle_path = os.path.join(sys.argv[1], m['file'])
     if not os.path.exists(bundle_path):
         print(f\"  WARN {m['id']}: bundle file not found ({m['file']})\")
         continue
@@ -112,8 +111,9 @@ for m in json.load(sys.stdin):
     for a in fm.get('actions_needed', []):
         v = a.get('verify', '')
         if v: print(f\"  verify: {v}\")
-" 2>/dev/null
+" "$MIGRATIONS_DIR" 2>/dev/null
 
   echo ""
   echo "Run without --dry-run to apply these migrations."
 }
+

package/scripts/lib/migrate-version-run.sh

@@ -28,6 +28,8 @@ migrate_version_main() {
 
   INSTALLED="$(migrate_installed_version)"
   migrate_detect_version || exit $?
+  migrate_validate_version "$DETECTED" detected || exit $?
+  migrate_validate_version "$INSTALLED" installed || exit $?
 
   echo "migrate-version: detected=$DETECTED installed=$INSTALLED"
 
@@ -51,3 +53,4 @@ migrate_version_main() {
   migrate_finalize
   exit 0
 }
+

package/scripts/lib/sync-post.sh

@@ -73,7 +73,7 @@ sync_post_run() {
     bash "$REPO_ROOT/scripts/build-skill-index.sh" || true
   fi
 
-  local CURSOR_KEEP="context7.mdc" mdc mdc_base
+  local CURSOR_KEEP="" mdc mdc_base
   for mdc in "$CURSOR_RULES"/*.mdc; do
     [[ -e "$mdc" ]] || continue
     mdc_base=$(basename "$mdc")

package/scripts/validate-skill-catalog.sh

@@ -18,7 +18,7 @@ VIOLATIONS=0
 WARNINGS=0
 
 # Documented naming exceptions (craft-skill REFERENCE.md)
-VERB_NOUN_EXCEPTIONS="grill-me grill-with-docs context7-mcp using-bigpowers deploy generate-allure-report"
+VERB_NOUN_EXCEPTIONS="grill-me grill-with-docs using-bigpowers deploy generate-allure-report"
 
 catalog_usage() {
   echo "Usage: bash scripts/validate-skill-catalog.sh [--archive] [--strict] [--skill <name>]"

package/skills-lock.json

@@ -41,11 +41,6 @@
       "sha256": "5dc23c0642af9d2b",
       "path": "skills/compose-workflow/SKILL.md"
     },
-    "context7-mcp": {
-      "description": "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc.",
-      "sha256": "f58dcec5aff6a0bf",
-      "path": "skills/context7-mcp/SKILL.md"
-    },
     "craft-skill": {
       "description": "Create new bigpowers skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill for the bigpowers lifecycle.",
       "sha256": "7acb068f458fa1b4",

package/tests/security/agents-import.cjs

@@ -0,0 +1,36 @@
+// story: e21s03
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'bp-agents-'));
+const script = path.resolve(__dirname, '../../scripts/bp-read-agents.sh');
+const commands = [
+  "echo'; printf IMPORT_RAN > import-marker; #",
+  "node -e 'console.log(\"quoted value\")'",
+  'echo $(touch substitution-marker) `touch backtick-marker` "$HOME"; echo done',
+  "printf '%s\\n' 'spaces & symbols | < >'",
+  'echo "deploy" && echo finished'
+];
+const names = ['PREFLIGHT', 'TEST', 'BUILD', 'LINT', 'DEPLOY'];
+const sections = ['Preflight', 'Test', 'Build', 'Lint', 'Deploy'];
+try {
+  for (const source of ['AGENTS.md', 'CLAUDE.md', 'CURSOR.md']) {
+    fs.writeFileSync(path.join(root, source), commands.map((c, i) =>
+      `## ${sections[i]}\n\n\`\`\`bash\n${c}\n\`\`\`\n`).join('\n'));
+    const output = execFileSync('bash', ['-c',
+      'eval "$(bash "$1")"; printf "%s\\0" "$BP_PREFLIGHT" "$BP_TEST" "$BP_BUILD" "$BP_LINT" "$BP_DEPLOY"',
+      'import-test', script], { cwd: root, encoding: 'utf8' });
+    for (const marker of ['import-marker', 'substitution-marker', 'backtick-marker']) {
+      assert(!fs.existsSync(path.join(root, marker)), `${source}: importing executed ${marker}`);
+    }
+    assert.deepStrictEqual(output.split('\0').slice(0, -1), commands, `${source}: exact values`);
+    const printed = execFileSync('bash', [script, '--print'], { cwd: root, encoding: 'utf8' });
+    for (const command of commands) assert(printed.includes(command));
+    fs.unlinkSync(path.join(root, source));
+  }
+  assert.strictEqual(execFileSync('bash', [script], { cwd: root, encoding: 'utf8' }), '');
+  console.log(`PASS: ${names.length} command exports round-trip without execution in all 3 source formats`);
+} finally { fs.rmSync(root, { recursive: true, force: true }); }

package/tests/security/dashboard-bind.cjs

@@ -0,0 +1,31 @@
+const assert = require('assert');
+const fs = require('fs');
+const http = require('http');
+const path = require('path');
+const vm = require('vm');
+
+// Replace filesystem watching and Express routing at the I/O boundary, but
+// exercise a real TCP listener with the arguments supplied by createServer.
+const filename = path.resolve(__dirname, '../../dashboard/src/web/server.js');
+const moduleStub = { exports: {} };
+const sandbox = {
+  module: moduleStub, __dirname: path.dirname(filename), console, setTimeout, clearTimeout,
+  require(name) {
+    if (name === 'path') return path;
+    if (name === '../loaders/watcher') return { watch: () => ({ on() {} }) };
+    if (name.startsWith('../loaders/')) return {};
+    assert.strictEqual(name, 'express');
+    return () => ({ get() {}, listen: (...args) => http.createServer().listen(...args) });
+  }
+};
+vm.runInNewContext(fs.readFileSync(filename, 'utf8'), sandbox, { filename });
+const app = moduleStub.exports.createServer('/unused', 0);
+const server = app.listen(0, () => {
+  try {
+    assert.strictEqual(server.address().address, '127.0.0.1');
+    assert(server.address().port > 0, 'ephemeral port and callback remain supported');
+    console.log('PASS: dashboard binds only to IPv4 loopback');
+  } catch (error) { console.error(error); process.exitCode = 1; }
+  finally { server.close(); }
+});
+server.on('error', error => { console.error(error); process.exitCode = 1; });

package/tests/security/dashboard-render.cjs

@@ -0,0 +1,60 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+// Execute the shipped client and feed its public fetch/SSE inputs. Capture
+// generated HTML at the DOM boundary; this is not a browser execution test.
+const nodes = new Map(['pipeline', 'metrics', 'state', 'epics', 'ledger', 'status']
+  .map(id => [id, { innerHTML: '', classList: { add() {}, remove() {} } }]));
+const events = new Map();
+let stream;
+const payload = '<img src=x onerror="window.__bpXss=1"> & \'quoted\'';
+const escaped = '&lt;img src=x onerror=&quot;window.__bpXss=1&quot;&gt; &amp; &#39;quoted&#39;';
+const snapshot = {
+  state: { activeFlow: payload, activeEpic: payload, activeStory: payload,
+    gitBranch: payload, release: { version: payload } },
+  projectMetrics: { totalBcps: payload, avgBcpPerHour: 1.5 },
+  currentVelocity: { avgBcpPerHour: 2 },
+  epics: [{ id: payload, title: payload, stories: [] }],
+  cycleTimes: [{ id: payload, bcps: payload, cycleMin: payload, bcpPerHour: 3 }]
+};
+const sandbox = {
+  console,
+  document: {
+    getElementById: id => nodes.get(id), querySelectorAll: () => [],
+    addEventListener() {}, createElement: () => ({ getContext: () => ({}) })
+  },
+  window: { addEventListener: (name, fn) => events.set(name, fn) },
+  fetch: async () => ({ json: async () => JSON.parse(JSON.stringify(snapshot)) }),
+  EventSource: class { constructor() { stream = this; } },
+  setInterval() { throw new Error('unexpected polling fallback'); }
+};
+const filename = path.resolve(__dirname, '../../dashboard/src/web/client.html');
+const html = fs.readFileSync(filename, 'utf8');
+for (const match of html.matchAll(/<script>([\s\S]*?)<\/script>/g)) {
+  vm.runInNewContext(match[1], sandbox, { filename });
+}
+function assertEscaped() {
+  for (const [panel, count] of [['state', 4], ['metrics', 2], ['epics', 2], ['ledger', 3]]) {
+    const output = nodes.get(panel).innerHTML;
+    assert(!output.includes('<img'), `${panel}: project metadata became HTML`);
+    assert.strictEqual(output.split(escaped).length - 1, count, `${panel}: literal text preserved`);
+  }
+}
+async function main() {
+  events.get('load')();
+  await new Promise(resolve => setImmediate(resolve));
+  assertEscaped();
+  assert(stream, 'initial fetch should connect SSE');
+  stream.onmessage({ data: JSON.stringify(snapshot) });
+  assertEscaped();
+  stream.onmessage({ data: JSON.stringify({ state: { gitBranch: 'feature/example' },
+    projectMetrics: { totalBcps: 0, avgBcpPerHour: 0 } }) });
+  assert(nodes.get('state').innerHTML.includes('feature/example'));
+  assert(nodes.get('metrics').innerHTML.includes('>0</span>'));
+  assert(nodes.get('epics').innerHTML.includes('No epics available'));
+  assert(nodes.get('ledger').innerHTML.includes('No cycle-time data available'));
+  console.log('PASS: fetch and SSE render all project metadata as escaped text');
+}
+main().catch(error => { console.error(error); process.exitCode = 1; });

package/tests/security/git-context.cjs

@@ -0,0 +1,44 @@
+// story: e32s04
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'bp-diff-'));
+const git = (...args) => execFileSync('git', args, { cwd: root, stdio: 'pipe' });
+const put = (name, value) => {
+  fs.mkdirSync(path.dirname(path.join(root, name)), { recursive: true });
+  fs.writeFileSync(path.join(root, name), value);
+};
+
+async function main() {
+  const { getGitContext } = await import('../../bigpowers-mcp/build/lib/git-context.js');
+  git('init', '-q');
+  const secret = 'specs/m-secret.pem';
+  const before = 'specs/a-public.md';
+  const after = 'specs/z-public.md';
+  const outside = 'private/readme.md';
+  for (const file of [secret, before, after, outside]) put(file, 'baseline\n');
+  git('add', '.');
+  git('-c', 'user.name=Test', '-c', 'user.email=test@example.invalid',
+    'commit', '-qm', 'fixture');
+  for (const allowed of [[after], [before, after], [before], []]) {
+    git('reset', '--hard', 'HEAD');
+    put(secret, 'DUMMY_SECRET_VALUE\n');
+    put(outside, 'OUT_OF_SCOPE_VALUE\n');
+    for (const file of allowed) put(file, 'PUBLIC_CHANGE\n');
+    const result = getGitContext(root, 'diff');
+    assert.deepStrictEqual(Object.keys(result.diffs).sort(), [...allowed].sort());
+    assert.deepStrictEqual(Object.values(result.changed_files).flat().sort(), [...allowed].sort());
+    assert(!JSON.stringify(result).includes('DUMMY_SECRET_VALUE'));
+    assert(!JSON.stringify(result).includes('OUT_OF_SCOPE_VALUE'));
+    for (const file of allowed) assert(result.diffs[file].includes('+PUBLIC_CHANGE'));
+  }
+  git('reset', '--hard', 'HEAD');
+  assert.deepStrictEqual(getGitContext(root, 'diff').diffs, {});
+  console.log('PASS: secret diffs excluded in first, middle, last and only positions');
+}
+
+main().catch(error => { console.error(error); process.exitCode = 1; })
+  .finally(() => fs.rmSync(root, { recursive: true, force: true }));

package/tests/security/migration.cjs

@@ -0,0 +1,76 @@
+// story: e44s03 e44s06
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync, spawnSync } = require('child_process');
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'bp-migration-'));
+const repo = path.resolve(__dirname, '../..');
+const project = path.join(root, 'project');
+const specs = path.join(project, 'specs');
+const marker = path.join(root, 'executed-marker');
+const git = (...args) => execFileSync('git', args, { cwd: project, stdio: 'pipe' });
+function stamp(version) {
+  fs.writeFileSync(path.join(specs, 'state.yaml'),
+    `bigpowers_version: ${JSON.stringify(version)}\nactive_flow: null\n`);
+  git('add', '.');
+  git('-c', 'user.name=Test', '-c', 'user.email=test@example.invalid',
+    'commit', '--allow-empty', '-qm', 'fixture');
+}
+function preview(script) {
+  const before = fs.readFileSync(path.join(specs, 'state.yaml'), 'utf8');
+  const result = spawnSync('bash', [script, '--project', project, '--dry-run'],
+    { cwd: project, encoding: 'utf8' });
+  assert(!result.error, String(result.error));
+  assert(!fs.existsSync(marker), 'dry run executed version metadata');
+  assert.strictEqual(fs.readFileSync(path.join(specs, 'state.yaml'), 'utf8'), before);
+  assert.deepStrictEqual(fs.readdirSync(specs), ['state.yaml'], 'dry run wrote files');
+  return result;
+}
+function copyFile(relative, destination) {
+  const target = path.join(destination, relative);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(path.join(repo, relative), target);
+}
+function installFixture(destination) {
+  for (const relative of ['package.json', 'scripts/migrate-version.sh',
+    'scripts/lib/python-env.sh', ...['common', 'plan', 'run', 'post', 'execute', 'transforms']
+      .map(name => `scripts/lib/migrate-version-${name}.sh`)]) copyFile(relative, destination);
+  const migrations = path.join(destination, 'specs/migrations');
+  fs.mkdirSync(migrations, { recursive: true });
+  fs.writeFileSync(path.join(migrations, 'registry.okf.md'),
+    '---\nmigrations:\n  - id: test\n    since_version: "2.80.0"\n    order: 1\n---\n');
+  fs.writeFileSync(path.join(migrations, 'test.okf.md'),
+    '---\ntransforms: []\nactions_needed: []\n---\n');
+  return path.join(destination, 'scripts/migrate-version.sh');
+}
+try {
+  fs.mkdirSync(specs, { recursive: true });
+  git('init', '-q', '-b', 'main');
+  const script = installFixture(path.join(root, 'installation'));
+  stamp(`0.0.0'; open('${marker}', 'w').write('DUMMY'); #`);
+  const hostile = preview(script);
+  assert.notStrictEqual(hostile.status, 0, 'invalid version must fail closed');
+  assert(/invalid.*version/i.test(hostile.stderr), hostile.stderr);
+  for (const version of ['1.0.0', '2.0.0', '2.20.0', '2.20.0-rc.1+build.2']) {
+    stamp(version);
+    const result = preview(script);
+    assert.strictEqual(result.status, 0, result.stderr);
+    assert(result.stdout.includes(`Detected version: ${version}`), result.stdout);
+  }
+  // The same data boundary applies to legitimate installation/project paths.
+  const installation = path.join(root, "install's directory");
+  const quotedScript = installFixture(installation);
+  stamp('1.0.0');
+  const quotedProject = path.join(root, "project's directory");
+  fs.symlinkSync(project, quotedProject, 'dir');
+  const result = spawnSync('bash', [quotedScript,
+    '--project', quotedProject, '--dry-run'], { encoding: 'utf8' });
+  assert.strictEqual(result.status, 0, result.stderr);
+  assert(result.stdout.includes('Detected version: 1.0.0'), result.stdout);
+  assert(result.stdout.includes('Transforms preview:'), result.stdout);
+  assert(result.stdout.includes('-- test: test --'), result.stdout);
+  assert(!result.stdout.includes('installed=unknown'), result.stdout);
+  console.log('PASS: migration preview rejects executable stamps and supports quoted paths');
+} finally { fs.rmSync(root, { recursive: true, force: true }); }

package/.agents/skills/context7-mcp/SKILL.md

@@ -1,55 +0,0 @@
----
-name: context7-mcp
-model: haiku
-description: "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc."
----
-
-# Context7 MCP
-
-> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data.
->
-> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get "<libraryId>:<query>"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry.
-
-## When to Use
-
-- Setup/configuration questions ("How do I configure Next.js middleware?")
-- Code involving libraries ("Write a Prisma query for…")
-- API references ("What are the Supabase auth methods?")
-- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)
-
-## Bounded Retry (max 3x)
-
-| Attempt | Action |
-|---------|--------|
-| 1 | `resolve-library-id` → pick best match |
-| 2 | `query-docs` with selected `libraryId` |
-| 3 | Retry `query-docs` once with refined query (narrower scope) |
-
-After 3 failures, stop and print:
-
-```
-CONTEXT7_UNAVAILABLE
-Reason: <quota|rate-limit|no-match|timeout>
-Action: Ask user to retry later, paste official docs URL, or run `bts docs <lib>`.
-Do NOT substitute training-data answers without labeling them UNVERIFIED.
-```
-
-## Fetch Cache (ETag-revalidated)
-
-1. **Cache key:** `"<libraryId>:<normalized-query>"` (lowercase, trimmed).
-2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get "<key>"` — exit 0 → use cached body.
-3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`.
-4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it.
-
-`bts docs <lib>` shares the same cache helper when invoked from this skill.
-
-## Process
-
-1. `resolve-library-id` with `libraryName` + full user `query`.
-2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version.
-3. `query-docs` with `libraryId` + specific question (one concept per call).
-4. Answer using fetched docs; cite library/version when relevant.
-
-## Verify
-
-→ verify: `test -f scripts/lib/doc-fetch-cache.sh`

package/.cline/skills/context7-mcp/SKILL.md

@@ -1,55 +0,0 @@
----
-name: context7-mcp
-model: haiku
-description: "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc."
----
-
-# Context7 MCP
-
-> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data.
->
-> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get "<libraryId>:<query>"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry.
-
-## When to Use
-
-- Setup/configuration questions ("How do I configure Next.js middleware?")
-- Code involving libraries ("Write a Prisma query for…")
-- API references ("What are the Supabase auth methods?")
-- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)
-
-## Bounded Retry (max 3x)
-
-| Attempt | Action |
-|---------|--------|
-| 1 | `resolve-library-id` → pick best match |
-| 2 | `query-docs` with selected `libraryId` |
-| 3 | Retry `query-docs` once with refined query (narrower scope) |
-
-After 3 failures, stop and print:
-
-```
-CONTEXT7_UNAVAILABLE
-Reason: <quota|rate-limit|no-match|timeout>
-Action: Ask user to retry later, paste official docs URL, or run `bts docs <lib>`.
-Do NOT substitute training-data answers without labeling them UNVERIFIED.
-```
-
-## Fetch Cache (ETag-revalidated)
-
-1. **Cache key:** `"<libraryId>:<normalized-query>"` (lowercase, trimmed).
-2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get "<key>"` — exit 0 → use cached body.
-3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`.
-4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it.
-
-`bts docs <lib>` shares the same cache helper when invoked from this skill.
-
-## Process
-
-1. `resolve-library-id` with `libraryName` + full user `query`.
-2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version.
-3. `query-docs` with `libraryId` + specific question (one concept per call).
-4. Answer using fetched docs; cite library/version when relevant.
-
-## Verify
-
-→ verify: `test -f scripts/lib/doc-fetch-cache.sh`

package/.codebuddy/skills/context7-mcp/SKILL.md

@@ -1,55 +0,0 @@
----
-name: context7-mcp
-model: haiku
-description: "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc."
----
-
-# Context7 MCP
-
-> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data.
->
-> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get "<libraryId>:<query>"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry.
-
-## When to Use
-
-- Setup/configuration questions ("How do I configure Next.js middleware?")
-- Code involving libraries ("Write a Prisma query for…")
-- API references ("What are the Supabase auth methods?")
-- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)
-
-## Bounded Retry (max 3x)
-
-| Attempt | Action |
-|---------|--------|
-| 1 | `resolve-library-id` → pick best match |
-| 2 | `query-docs` with selected `libraryId` |
-| 3 | Retry `query-docs` once with refined query (narrower scope) |
-
-After 3 failures, stop and print:
-
-```
-CONTEXT7_UNAVAILABLE
-Reason: <quota|rate-limit|no-match|timeout>
-Action: Ask user to retry later, paste official docs URL, or run `bts docs <lib>`.
-Do NOT substitute training-data answers without labeling them UNVERIFIED.
-```
-
-## Fetch Cache (ETag-revalidated)
-
-1. **Cache key:** `"<libraryId>:<normalized-query>"` (lowercase, trimmed).
-2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get "<key>"` — exit 0 → use cached body.
-3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`.
-4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it.
-
-`bts docs <lib>` shares the same cache helper when invoked from this skill.
-
-## Process
-
-1. `resolve-library-id` with `libraryName` + full user `query`.
-2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version.
-3. `query-docs` with `libraryId` + specific question (one concept per call).
-4. Answer using fetched docs; cite library/version when relevant.
-
-## Verify
-
-→ verify: `test -f scripts/lib/doc-fetch-cache.sh`

package/.codex/skills/context7-mcp/SKILL.md

@@ -1,55 +0,0 @@
----
-name: context7-mcp
-model: haiku
-description: "Fetch current library docs via Context7 MCP instead of training data. Use when user asks about frameworks, APIs, setup, or code examples for React, Next.js, Prisma, etc."
----
-
-# Context7 MCP
-
-> **HARD GATE** — Max **3** Context7 tool calls per user question (`resolve-library-id` + `query-docs` count toward the cap). On quota/rate-limit errors, emit an explicit **CONTEXT7_UNAVAILABLE** block — do NOT silently answer from training data.
->
-> **HARD GATE** — Before HTTP fetch, check `bash scripts/lib/doc-fetch-cache.sh get "<libraryId>:<query>"`. Cache hit within TTL → use cached body (no round-trip). On ETag mismatch after conditional refresh, replace cache entry.
-
-## When to Use
-
-- Setup/configuration questions ("How do I configure Next.js middleware?")
-- Code involving libraries ("Write a Prisma query for…")
-- API references ("What are the Supabase auth methods?")
-- User mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)
-
-## Bounded Retry (max 3x)
-
-| Attempt | Action |
-|---------|--------|
-| 1 | `resolve-library-id` → pick best match |
-| 2 | `query-docs` with selected `libraryId` |
-| 3 | Retry `query-docs` once with refined query (narrower scope) |
-
-After 3 failures, stop and print:
-
-```
-CONTEXT7_UNAVAILABLE
-Reason: <quota|rate-limit|no-match|timeout>
-Action: Ask user to retry later, paste official docs URL, or run `bts docs <lib>`.
-Do NOT substitute training-data answers without labeling them UNVERIFIED.
-```
-
-## Fetch Cache (ETag-revalidated)
-
-1. **Cache key:** `"<libraryId>:<normalized-query>"` (lowercase, trimmed).
-2. **Read:** `bash scripts/lib/doc-fetch-cache.sh get "<key>"` — exit 0 → use cached body.
-3. **Miss / stale:** call `query-docs`; store via `doc-fetch-cache.sh put`.
-4. **TTL:** 300s default (`DOC_CACHE_TTL`). Stale entries refresh on next fetch; honor `ETag` when MCP returns it.
-
-`bts docs <lib>` shares the same cache helper when invoked from this skill.
-
-## Process
-
-1. `resolve-library-id` with `libraryName` + full user `query`.
-2. Select match: name similarity, reputation, benchmark score; prefer version-specific IDs when user names a version.
-3. `query-docs` with `libraryId` + specific question (one concept per call).
-4. Answer using fetched docs; cite library/version when relevant.
-
-## Verify
-
-→ verify: `test -f scripts/lib/doc-fetch-cache.sh`