contextos-agents 2.1.1 → 2.3.0

package/.agents/generated/gemini/skills/security/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/.agents/plugins.js

@@ -47,6 +47,25 @@ const REGISTRY_URL   = 'https://raw.githubusercontent.com/kok-o/contextos-agents
 const MAX_DOWNLOAD_BYTES = 5 * 1024 * 1024;
 const SAFE_SKILL_NAME = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
 
+function getCatalogDir() {
+  if (process.env.CONTEXTOS_CATALOG_DIR && fs.existsSync(process.env.CONTEXTOS_CATALOG_DIR)) {
+    return process.env.CONTEXTOS_CATALOG_DIR;
+  }
+  const localAgentsCatalog = path.join(__dirname, 'catalog', 'skills');
+  if (fs.existsSync(localAgentsCatalog)) return localAgentsCatalog;
+
+  const relativeCatalog = path.join(path.resolve(__dirname, '..'), 'catalog', 'skills');
+  if (fs.existsSync(relativeCatalog)) return relativeCatalog;
+
+  try {
+    const pkgPath = require.resolve('contextos-agents/package.json', { paths: [__dirname, process.cwd()] });
+    const pkgCatalog = path.join(path.dirname(pkgPath), 'catalog', 'skills');
+    if (fs.existsSync(pkgCatalog)) return pkgCatalog;
+  } catch {}
+
+  return null;
+}
+
 // ── ANSI helpers ──────────────────────────────────────────────────────────────
 const NO_COLOR = process.env.NO_COLOR || !process.stdout.isTTY;
 const c = {
@@ -291,7 +310,7 @@ function parseRef(ref, projectRoot = null) {
 
   // 1. Built-in package catalog skills take strict precedence for catalog names.
   // Consumer project local files can never spoof or hijack package catalog skills.
-  const pkgCatalogPath = path.join(path.resolve(__dirname, '..'), 'catalog', 'skills', ref);
+  const pkgCatalogPath = path.join(getCatalogDir(), ref);
   if (fs.existsSync(pkgCatalogPath) && fs.existsSync(path.join(pkgCatalogPath, 'SKILL.md'))) {
     return {
       type: 'catalog',
@@ -636,9 +655,137 @@ function isSafeSkillName(skillName) {
   return typeof skillName === 'string' && SAFE_SKILL_NAME.test(skillName);
 }
 
-// ═════════════════════════════════════════════════════════════════════════════
-//  COMMANDS
-// ═════════════════════════════════════════════════════════════════════════════
+function findClosestSkill(target, candidates) {
+  let closest = null;
+  let minDistance = Infinity;
+  for (const item of candidates) {
+    if (item === target) return item;
+    if (item.includes(target) || target.includes(item)) return item;
+    const dist = levenshtein(target, item);
+    if (dist < minDistance && dist <= 3) {
+      minDistance = dist;
+      closest = item;
+    }
+  }
+  return closest;
+}
+
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const d = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) d[i][0] = i;
+  for (let j = 0; j <= n; j++) d[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+    }
+  }
+  return d[m][n];
+}
+
+/**
+ * Batch install all available catalog skills.
+ */
+async function addAllFromCatalog(options = {}) {
+  const dryRun = Boolean(options.dryRun || options['dry-run']);
+  const force = Boolean(options.force);
+  const catalogDir = getCatalogDir();
+  if (!fs.existsSync(catalogDir)) {
+    throw new Error('Catalog directory not found in package');
+  }
+
+  const catalogSkills = fs.readdirSync(catalogDir).filter(n => {
+    const full = path.join(catalogDir, n);
+    return fs.statSync(full).isDirectory() && fs.existsSync(path.join(full, 'SKILL.md'));
+  });
+
+  console.log('');
+  console.log(c.bold(`Batch installing ${catalogSkills.length} catalog skills...`));
+
+  const lock = readLock();
+  const existingNames = new Set(lock.plugins.map(p => p.name));
+
+  const projectLock = new ProjectMutationLock(ROOT);
+  const tx = new JournaledTransaction(ROOT);
+  let lockToken = null;
+
+  let installedCount = 0;
+  let skippedCount = 0;
+  const newlyInstalled = [];
+
+  try {
+    lockToken = projectLock.acquire({ command: 'skill:add-all' });
+
+    for (const skillName of catalogSkills) {
+      if (existingNames.has(skillName) && !force) {
+        skippedCount++;
+        continue;
+      }
+
+      const descriptor = {
+        type: 'catalog',
+        name: skillName,
+        path: path.join(catalogDir, skillName),
+        isPinned: true,
+        raw: skillName,
+      };
+
+      const installedSha256 = installFromCatalog(descriptor, skillName, dryRun, null, false, tx);
+
+      if (!dryRun) {
+        const idx = lock.plugins.findIndex(p => p.name === skillName);
+        const entry = {
+          name: skillName,
+          ref: skillName,
+          type: 'catalog',
+          sha256: installedSha256,
+          installedAt: new Date().toISOString(),
+        };
+        if (idx >= 0) lock.plugins[idx] = entry;
+        else lock.plugins.push(entry);
+        newlyInstalled.push(skillName);
+      }
+      installedCount++;
+    }
+
+    if (!dryRun) {
+      writeLock(lock, tx);
+      tx.commit();
+
+      for (const skillName of newlyInstalled) {
+        const targetDir = path.join(PLUGINS_DIR, skillName);
+        if (fs.existsSync(targetDir)) {
+          const digestResult = calculateTreeDigest(targetDir);
+          const entry = lock.plugins.find(p => p.name === skillName);
+          if (entry) entry.treeDigest = digestResult.treeDigest;
+        }
+      }
+      writeLock(lock);
+    }
+
+    console.log('');
+    if (dryRun) {
+      console.log(c.dim(`[DRY-RUN] Would install ${installedCount} skills (${skippedCount} already installed - skipped).`));
+    } else {
+      console.log(c.green(c.bold(`✓ Batch install complete: ${installedCount} catalog skills installed.`)));
+      if (skippedCount > 0) {
+        console.log(c.dim(`  (${skippedCount} skills already installed - skipped)`));
+      }
+      console.log('');
+      console.log('  Next steps:');
+      console.log('    node .agents/ctx.js export all    # recompile with new skills');
+      console.log('    node .agents/ctx.js validate      # verify consistency');
+    }
+
+    return { installedCount, skippedCount };
+  } catch (err) {
+    console.error(c.red(`\n[ERROR] Batch installation failed: ${err.message}`));
+    process.exit(1);
+  } finally {
+    if (lockToken) projectLock.release(lockToken);
+  }
+}
 
 /**
  * skill add <ref> [--dry-run] [--checksum <sha256>] [--force-unsafe-prompts]
@@ -650,6 +797,10 @@ async function add(ref, options = {}) {
   const allowFloating = Boolean(options.allowFloating || options['allow-floating']);
   const force = Boolean(options.force);
 
+  if (ref === '--all' || ref === 'all' || options.all) {
+    return await addAllFromCatalog(options);
+  }
+
   if (!ref) {
     console.error(c.red('Usage: ctx.js skill add <ref> [--checksum <sha256>]'));
     console.error('  ref can be: username/repo, username/repo/path/to/skill, or npm-package-name');
@@ -663,7 +814,37 @@ async function add(ref, options = {}) {
     throw new Error(`Invalid plugin name derived from reference: '${skillName}'`);
   }
 
-  // Supply-chain source pinning check (Wave 6)
+  // 1. Check for conflict with builtin skills first
+  const builtinPath = path.join(CORE_SKILLS, skillName);
+  if (fs.existsSync(builtinPath)) {
+    console.error(c.red(`\n[ERROR] '${skillName}' conflicts with a built-in skill.`));
+    console.error(c.red('  Built-in skills cannot be overridden via --add-skill.'));
+    console.error(c.dim(`  To customize a built-in skill for your project, run: contextos skill override ${skillName}`));
+    process.exit(1);
+  }
+
+  // 2. If single word not in catalog, check for typo suggestion
+  if (descriptor.type !== 'catalog' && !ref.includes('/') && !ref.includes('@')) {
+    const catalogDir = getCatalogDir();
+    if (fs.existsSync(catalogDir)) {
+      const catalogSkills = fs.readdirSync(catalogDir).filter(n => {
+        try {
+          return fs.statSync(path.join(catalogDir, n)).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+      const suggestion = findClosestSkill(skillName, catalogSkills);
+      if (suggestion) {
+        console.error(c.red(`\n[ERROR] Skill '${skillName}' not found in catalog.`));
+        console.log(c.yellow(`  Did you mean: "${suggestion}"?`));
+        console.log(c.dim('  Run "contextos skill list --available" to see all catalog skills.'));
+        process.exit(1);
+      }
+    }
+  }
+
+  // 3. Supply-chain source pinning check (Wave 6)
   if (!dryRun && descriptor.type !== 'catalog') {
     const pinning = validatePluginPinning(
       {
@@ -688,15 +869,6 @@ async function add(ref, options = {}) {
   console.log(c.bold(`Installing skill: ${c.cyan(skillName)}`));
   console.log(c.dim(`  Source: ${ref} (${descriptor.type})`));
 
-  // Check for conflict with builtin skills
-  const builtinPath = path.join(CORE_SKILLS, skillName);
-  if (fs.existsSync(builtinPath)) {
-    console.error(c.red(`\n[ERROR] '${skillName}' conflicts with a built-in skill.`));
-    console.error(c.red('  Built-in skills cannot be overridden via --add-skill.'));
-    console.error(c.dim('  To customize a built-in skill, fork the repo and submit a PR.'));
-    process.exit(1);
-  }
-
   // Check if already installed
   const lock     = readLock();
   const existing = lock.plugins.find(p => p.name === skillName);
@@ -779,6 +951,21 @@ async function add(ref, options = {}) {
       // We don't need to do anything since it wasn't committed
     }
     console.error(c.red(`\n[ERROR] Failed to install '${skillName}': ${err.message}`));
+    const catalogDir = getCatalogDir();
+    if (fs.existsSync(catalogDir)) {
+      const catalogSkills = fs.readdirSync(catalogDir).filter(n => {
+        try {
+          return fs.statSync(path.join(catalogDir, n)).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+      const suggestion = findClosestSkill(skillName, catalogSkills);
+      if (suggestion) {
+        console.log(c.yellow(`  Did you mean: "${suggestion}"?`));
+        console.log(c.dim('  Run "contextos skill list --available" to see all catalog skills.'));
+      }
+    }
     process.exit(1);
   } finally {
     if (lockToken) projectLock.release(lockToken);
@@ -898,25 +1085,46 @@ function remove(skillName) {
 }
 
 /**
- * skill list
+ * skill list [options]
  */
-function list() {
+function list(options = {}) {
+  const showAvailable = Boolean(options.available || options['--available'] || options.all);
   const lock = readLock();
 
   // Builtin skills
   const builtins = fs.existsSync(CORE_SKILLS)
-    ? fs.readdirSync(CORE_SKILLS).filter(n => fs.statSync(path.join(CORE_SKILLS, n)).isDirectory())
+    ? fs.readdirSync(CORE_SKILLS).filter(n => {
+        try {
+          return fs.statSync(path.join(CORE_SKILLS, n)).isDirectory();
+        } catch {
+          return false;
+        }
+      })
     : [];
 
   // Plugin skills
   const plugins = lock.plugins;
 
+  // Catalog skills
+  const catalogDir = getCatalogDir();
+  const catalogSkills = fs.existsSync(catalogDir)
+    ? fs.readdirSync(catalogDir).filter(n => {
+        try {
+          return fs.statSync(path.join(catalogDir, n)).isDirectory();
+        } catch {
+          return false;
+        }
+      })
+    : [];
+  const installedNames = new Set(plugins.map(p => p.name));
+  const availableCatalog = catalogSkills.filter(n => !installedNames.has(n));
+
   console.log('');
   console.log(c.bold('ContextOS Skills'));
   console.log('');
 
   // Built-ins
-  console.log(c.bold(`  Built-in (${builtins.length})`));
+  console.log(c.bold(`  Built-in Core (${builtins.length})`));
   for (const name of builtins) {
     console.log(`    ${c.cyan('●')} ${name}  ${c.dim('(core)')}`);
   }
@@ -924,22 +1132,39 @@ function list() {
   // Plugins
   console.log('');
   if (plugins.length === 0) {
-    console.log(c.bold('  Plugins (0)'));
-    console.log(c.dim('    No plugins installed yet.'));
-    console.log(c.dim('    Install one: node .agents/ctx.js skill add username/my-skill'));
+    console.log(c.bold('  Installed Plugins & Domain Skills (0)'));
+    console.log(c.dim('    No domain skills or plugins installed yet.'));
+    console.log(c.dim('    Install one: contextos skill add <name>  (or --all)'));
   } else {
-    console.log(c.bold(`  Plugins (${plugins.length})`));
+    console.log(c.bold(`  Installed Plugins & Domain Skills (${plugins.length})`));
     for (const p of plugins) {
       const when = p.installedAt ? new Date(p.installedAt).toLocaleDateString() : '?';
       console.log(`    ${c.green('●')} ${p.name}  ${c.dim(`← ${p.ref}  (installed ${when})`)}`);
     }
   }
 
+  // Available in Catalog
+  console.log('');
+  if (showAvailable || availableCatalog.length > 0) {
+    console.log(c.bold(`  Available in Catalog (${availableCatalog.length})`));
+    if (showAvailable) {
+      for (const name of availableCatalog) {
+        console.log(`    ${c.dim('○')} ${name}`);
+      }
+      console.log('');
+      console.log(c.dim('  Install with: contextos skill add <name>  (or contextos skill add --all)'));
+    } else {
+      console.log(c.dim(`    ${availableCatalog.length} domain skills available in local catalog.`));
+      console.log(c.dim('    Run "contextos skill list --available" to see all, or install with:'));
+      console.log(c.dim('    contextos skill add <name>  |  contextos skill add --all'));
+    }
+  }
+
   console.log('');
 }
 
 /**
- * skill search <query>  — searches the hosted registry.json
+ * skill search <query> - searches the hosted registry.json
  */
 async function search(query) {
   console.log(c.dim(`\nFetching registry from: ${REGISTRY_URL}\n`));
@@ -996,11 +1221,11 @@ async function search(query) {
  * both core (builtin) and plugins.
  * Adapters call this instead of reading CORE_SKILLS directly.
  */
-function collectAllSkillDirs(targetRoot) {
+function collectAllSkillDirs(targetRoot, options = {}) {
   const isTargetExplicit = Boolean(targetRoot);
   const root = targetRoot || process.cwd();
-  const agentsDir = path.join(root, '.agents');
-  const localCore = path.join(agentsDir, 'core', 'skills');
+  const agentsDir = options.agentsDir || path.join(root, '.agents');
+  const localCore = options.coreSkillsDir || path.join(agentsDir, 'core', 'skills');
   const localPlugins = path.join(agentsDir, 'plugins');
 
   const coreDir = fs.existsSync(localCore) ? localCore : (isTargetExplicit ? null : CORE_SKILLS);
@@ -1027,13 +1252,32 @@ function collectAllSkillDirs(targetRoot) {
           const subDir = path.join(nestedSkills, sub);
           if (fs.statSync(subDir).isDirectory()) dirs.push(subDir);
         }
-      } else if (fs.existsSync(path.join(d, 'SKILL.md')) || fs.existsSync(path.join(d, 'skill.yaml'))) {
+      } else if (fs.existsSync(path.join(d, 'SKILL.md')) || fs.existsSync(path.join(d, 'skill.yaml')) || fs.existsSync(path.join(d, 'skill.v2.yaml'))) {
         dirs.push(d);
       }
     }
   }
 
-  return dirs;
+  // Higher ownership tiers replace an upstream skill with the same ID. Preserve
+  // upstream duplicates so the compiler can still diagnose conflicting installs.
+  for (const tier of ['vendor', 'project']) {
+    const tierRoot = path.join(agentsDir, tier, 'skills');
+    if (!fs.existsSync(tierRoot)) continue;
+    for (const name of fs.readdirSync(tierRoot).sort()) {
+      const dir = path.join(tierRoot, name);
+      const { resolvedPath } = require('./filesystem/index.js').resolveManagedPath(root, path.relative(root, dir));
+      if (!fs.statSync(resolvedPath).isDirectory()) continue;
+      if (!fs.existsSync(path.join(dir, 'SKILL.md')) && !fs.existsSync(path.join(dir, 'skill.yaml')) && !fs.existsSync(path.join(dir, 'skill.v2.yaml'))) continue;
+      for (let i = dirs.length - 1; i >= 0; i--) {
+        if (path.basename(dirs[i]) === name) dirs.splice(i, 1);
+      }
+      dirs.push(dir);
+    }
+  }
+  if (isTargetExplicit) {
+    for (const dir of dirs) require('./filesystem/index.js').resolveManagedPath(root, path.relative(root, dir));
+  }
+  return dirs.sort();
 }
 
 module.exports = {

package/.agents/resolver/canonical-resolver.js

@@ -650,6 +650,12 @@ class CanonicalResolver {
         }
       }
 
+      if (resolvedId === 'security' && ['keyword', 'file_glob', 'explicit', 'safety_required'].includes(kind)) {
+        if (profileExcluded.delete(resolvedId)) {
+          warnings.push({ code: 'CTX_REQUIRED_SECURITY_PROFILE_CONFLICT', message: 'Task safety guidance overrides the profile exclusion of security.' });
+        }
+        kind = 'safety_required';
+      }
       if (profileExcluded.has(resolvedId)) return;
       if (!evidenceBySkill.has(resolvedId)) evidenceBySkill.set(resolvedId, []);
       evidenceBySkill.get(resolvedId).push({ kind, weight, reason });
@@ -836,6 +842,10 @@ class CanonicalResolver {
       }
     }
 
+    if (risk.value === 'high' || risk.value === 'destructive') {
+      addEvidence('security', 'safety_required', 100, `Required safety guidance for ${risk.value} risk task`);
+    }
+
     // 3. Compute Candidate Scores & Intent Precedence
     const candidates = [];
     for (const [id, evList] of evidenceBySkill.entries()) {
@@ -850,7 +860,7 @@ class CanonicalResolver {
         if ((e.kind === 'keyword' || e.kind === 'alias') && e.weight >= 20) {
           hasDirectTaskIntent = true;
         }
-        if (e.kind === 'explicit' || e.kind === 'profile_required') {
+        if (e.kind === 'explicit' || e.kind === 'profile_required' || e.kind === 'safety_required') {
           isMandatory = true;
           hasDirectTaskIntent = true;
         }
@@ -929,7 +939,7 @@ class CanonicalResolver {
     const closureMap = new Map();
     for (const item of initialSelection) {
       const rawEst = skillsDict[item.id]?.estimatedTokens || 1000;
-      const estTokens = Math.min(rawEst, BUDGET_TIERS.SKILL_BODY);
+      const estTokens = rawEst;
       closureMap.set(item.id, {
         id: item.id,
         displayName: skillsDict[item.id]?.displayName || item.id,
@@ -953,7 +963,7 @@ class CanonicalResolver {
           }
         } else {
           const rawEst = skillsDict[reqId]?.estimatedTokens || 1000;
-          const estTokens = Math.min(rawEst, BUDGET_TIERS.SKILL_BODY);
+          const estTokens = rawEst;
           closureMap.set(reqId, {
             id: reqId,
             displayName: skillsDict[reqId]?.displayName || reqId,
@@ -1000,7 +1010,12 @@ class CanonicalResolver {
     }
 
     // 7. Token Budget Planner & Capability Clustering
-    const BASE_SKILLS = ['ponytail-mindset', 'engineering-workflow'];
+    const plannedPhase = resolvePhaseAndRole(explicitPhase, task, []).phase.value;
+    const BASE_SKILLS = ['engineering-workflow'];
+    if (risk.value !== 'routine' && plannedPhase === 'Build') BASE_SKILLS.push('ponytail-mindset');
+    for (let i = BASE_SKILLS.length - 1; i >= 0; i--) {
+      if (!skillsDict[BASE_SKILLS[i]]) BASE_SKILLS.splice(i, 1);
+    }
     let baseTokens = 0;
 
     for (const baseId of BASE_SKILLS) {
@@ -1009,7 +1024,8 @@ class CanonicalResolver {
       }
     }
 
-    let allocatedDynamicTokens = 0;
+    // Foundation bodies occupy the same budget as task-specific skills.
+    let allocatedDynamicTokens = baseTokens;
     const admitted = new Map(); // id -> candidate entry
 
     // Separate mandatory vs optional candidates
@@ -1017,7 +1033,7 @@ class CanonicalResolver {
     const optionalCandidates = [];
 
     for (const cand of closureMap.values()) {
-      const isMandatory = cand.reasons.some(r => r.kind === 'explicit' || r.kind === 'profile_required');
+      const isMandatory = cand.reasons.some(r => r.kind === 'explicit' || r.kind === 'profile_required' || r.kind === 'safety_required');
       if (isMandatory) {
         mandatoryCandidates.push(cand);
       } else {
@@ -1131,6 +1147,25 @@ class CanonicalResolver {
       }
     }
 
+    const totalSelectedTokens = finalSelected.reduce((sum, skill) => sum + skill.estimatedTokens, 0);
+    for (const skill of finalSelected) {
+      if (!skillsDict[skill.id]) {
+        warnings.push({ code: 'CTX_SELECTED_SKILL_UNAVAILABLE', message: `Selected skill "${skill.id}" has no installed manifest. Install it before assembling runtime context.` });
+      }
+    }
+    if (finalSelected.length > maxSkillsLimit) {
+      warnings.push({ code: 'CTX_RESOLVER_SKILL_LIMIT_EXCEEDED', message: `Required skills and dependencies occupy ${finalSelected.length} slots; soft maxSkills limit is ${maxSkillsLimit}.` });
+    }
+    if (finalSelected.length > maxSkillsLimit) {
+      warnings.push({ code: 'CTX_RESOLVER_SKILL_LIMIT_EXCEEDED', message: `Required skills and dependencies occupy ${finalSelected.length} slots; soft maxSkills limit is ${maxSkillsLimit}.` });
+    }
+    if (totalSelectedTokens > budgetTokens && !warnings.some(w => w.code === 'CTX_RESOLVER_BUDGET_EXCEEDED')) {
+      warnings.push({
+        code: 'CTX_RESOLVER_BUDGET_EXCEEDED',
+        message: `Soft context budget (${budgetTokens} tokens) exceeded by required/foundation skill bodies (total: ${totalSelectedTokens} tokens). Client instructions and chat history are additional.`,
+      });
+    }
+
     // 9. Domain, Phase & Role
     let domain = request.domain || '';
     if (!domain) {
@@ -1208,7 +1243,7 @@ class CanonicalResolver {
       excluded,
       conflicts,
       warnings,
-      totalEstimatedTokens: baseTokens + allocatedDynamicTokens,
+      totalEstimatedTokens: totalSelectedTokens,
       // Legacy compatibility properties
       skills: allSelectedIds,
     };
@@ -1229,6 +1264,7 @@ class CanonicalResolver {
     const lines = [
       `[DOMAIN: ${res.domain}] [PHASE: ${phaseStr}] [ROLE: ${res.role}] [MODE: ${modeStr}] [LENSES: ${lensesStr}] [RISK: ${riskStr}]`,
       `Skills loaded: ${skillsList}`,
+      'Selection declaration only; skill bodies are read by the consuming client or prompt assembler.',
     ];
     if (res.workflow && res.workflow.steps && res.workflow.steps.length > 0) {
       lines.push(`Workflow (${res.workflow.name}): ${res.workflow.steps[0]}`);

package/.agents/resolver/resolve-args.js

@@ -0,0 +1,31 @@
+'use strict';
+
+function parseResolveArgs(args) {
+  const result = { task: '', files: [], explicitPhase: undefined, contextBudgetTokens: undefined, json: false, explain: false };
+  const task = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') result.json = true;
+    else if (arg === '--explain') result.explain = true;
+    else if (['--files', '--phase', '--budget'].includes(arg)) {
+      const value = args[++i];
+      if (!value || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      if (arg === '--files') result.files = value.split(',').map(file => file.trim()).filter(Boolean);
+      else if (arg === '--phase') result.explicitPhase = value;
+      else {
+        if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))) {
+          throw new Error('--budget must be a positive integer');
+        }
+        result.contextBudgetTokens = Number(value);
+      }
+    } else if (arg === '--') {
+      task.push(...args.slice(i + 1));
+      break;
+    } else if (arg.startsWith('-')) throw new Error(`Unknown resolve option: ${arg}`);
+    else task.push(arg);
+  }
+  result.task = task.join(' ');
+  return result;
+}
+
+module.exports = { parseResolveArgs };

package/.agents/stats.js

@@ -6,7 +6,7 @@
  *   1. Full context payload (all skills + AGENTS.md)
  *   2. Profiled context payload (after applying active profile exclusions)
  *   3. Dynamically resolved context (lean on-demand skill set for typical tasks)
- *   4. Concrete token savings percentage and cost reductions
+ *   4. Character-based payload estimates, not provider billing or quality results
  */
 
 'use strict';
@@ -22,7 +22,6 @@ function estimateTokens(text) {
 
 function calculateContextStats(projectDir = process.cwd()) {
   const agentsDir = path.join(projectDir, '.agents');
-  const skillsDir = path.join(agentsDir, 'core', 'skills');
   const agentsMdPath = path.join(agentsDir, 'AGENTS.md');
 
   let agentsMdChars = 0;
@@ -31,15 +30,13 @@ function calculateContextStats(projectDir = process.cwd()) {
   }
 
   const skillCharMap = new Map();
-  if (fs.existsSync(skillsDir)) {
-    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const skillMd = path.join(skillsDir, entry.name, 'SKILL.md');
+  const { collectSkillDirectories } = require('./adapters/shared.js');
+  const allDirs = collectSkillDirectories({ exclude_skills: [] }, projectDir);
+  for (const directory of allDirs) {
+      const skillMd = path.join(directory, 'SKILL.md');
       if (fs.existsSync(skillMd)) {
-        skillCharMap.set(entry.name, fs.readFileSync(skillMd, 'utf8').length);
+        skillCharMap.set(path.basename(directory), fs.readFileSync(skillMd, 'utf8').length);
       }
-    }
   }
 
   const totalSkillCount = skillCharMap.size;
@@ -50,9 +47,9 @@ function calculateContextStats(projectDir = process.cwd()) {
 
   // Active profile
   const activeProfile = profiles.getActiveProfile(projectDir);
-  const profileName = activeProfile ? (activeProfile.name || activeProfile.profile) : 'startup (recommended)';
+  const profileName = activeProfile ? (activeProfile.name || activeProfile.profile) : 'none';
   const excludedSkills = new Set(
-    activeProfile ? activeProfile.exclude_skills || [] : (profiles.getProfile('startup')?.exclude_skills || [])
+    activeProfile ? activeProfile.exclude_skills || [] : []
   );
 
   let profileChars = agentsMdChars;

package/.agents/workspace/workspace-graph.js

@@ -23,6 +23,8 @@ const DEFAULT_IGNORED_DIRS = new Set([
   '.git',
   'node_modules',
   '.contextos-worktrees',
+  '.swarm-worktrees',
+  '.external-skills',
   '.agents',
   'dist',
   'build',
@@ -121,6 +123,7 @@ class WorkspaceGraphBuilder {
     this.maxDepth = options.maxDepth || 8;
     this.maxPackages = options.maxPackages || 500;
     this.ignoredDirs = new Set([...DEFAULT_IGNORED_DIRS, ...(options.ignoredDirs || [])]);
+    this.includeNestedRepositories = options.includeNestedRepositories === true;
   }
 
   /**
@@ -223,7 +226,11 @@ class WorkspaceGraphBuilder {
         return;
       }
 
-      for (const entry of entries) {
+      for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (packages.length >= this.maxPackages) {
+          hitLimit = true;
+          break;
+        }
         if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
         if (this.ignoredDirs.has(entry.name)) continue;
 
@@ -236,10 +243,8 @@ class WorkspaceGraphBuilder {
         }
 
         // Symlink escape guard: must remain within root realpath
-        if (
-          !realEntryPath.startsWith(visitedDirs.values().next().value) &&
-          !realEntryPath.startsWith(realRoot)
-        ) {
+        const realRelative = path.relative(realRoot, realEntryPath);
+        if (realRelative === '..' || realRelative.startsWith(`..${path.sep}`) || path.isAbsolute(realRelative)) {
           continue;
         }
 
@@ -253,7 +258,12 @@ class WorkspaceGraphBuilder {
           workspaceGlobs.length === 0 ||
           workspaceGlobs.some((g) => g.test(relPath));
 
-        const pkg = this._inspectDirectoryForPackage(fullPath, relPath, realRoot);
+        if (fs.existsSync(path.join(fullPath, '.git')) &&
+            !this.includeNestedRepositories && !(workspaceGlobs.length > 0 && isDeclared)) {
+          continue;
+        }
+
+        const pkg = isDeclared ? this._inspectDirectoryForPackage(fullPath, relPath, realRoot) : null;
         if (pkg) {
           packages.push(pkg);
           packageIdSet.add(pkg.id);