cap-pro 1.0.0

package/cap/bin/lib/model-profiles.cjs

@@ -0,0 +1,69 @@
+// @cap-feature(feature:F-011) Legacy GSD Modules — model profile mapping (quality/balanced/budget per agent)
+/**
+ * Mapping of GSD agent to model for each profile.
+ *
+ * Should be in sync with the profiles table in `cap/references/model-profiles.md`. But
+ * possibly worth making this the single source of truth at some point, and removing the markdown
+ * reference table in favor of programmatically determining the model to use for an agent (which
+ * would be faster, use fewer tokens, and be less error-prone).
+ */
+const MODEL_PROFILES = {
+  'gsd-planner': { quality: 'opus', balanced: 'opus', budget: 'sonnet' },
+  'gsd-roadmapper': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+  'gsd-executor': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+  'gsd-phase-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-project-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-research-synthesizer': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-debugger': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+  'gsd-codebase-mapper': { quality: 'sonnet', balanced: 'haiku', budget: 'haiku' },
+  'gsd-verifier': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-plan-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-integration-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-nyquist-auditor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-ui-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-ui-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-ui-auditor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+};
+const VALID_PROFILES = Object.keys(MODEL_PROFILES['gsd-planner']);
+
+/**
+ * Formats the agent-to-model mapping as a human-readable table (in string format).
+ *
+ * @param {Object<string, string>} agentToModelMap - A mapping from agent to model
+ * @returns {string} A formatted table string
+ */
+function formatAgentToModelMapAsTable(agentToModelMap) {
+  const agentWidth = Math.max('Agent'.length, ...Object.keys(agentToModelMap).map((a) => a.length));
+  const modelWidth = Math.max(
+    'Model'.length,
+    ...Object.values(agentToModelMap).map((m) => m.length)
+  );
+  const sep = '─'.repeat(agentWidth + 2) + '┼' + '─'.repeat(modelWidth + 2);
+  const header = ' ' + 'Agent'.padEnd(agentWidth) + ' │ ' + 'Model'.padEnd(modelWidth);
+  let agentToModelTable = header + '\n' + sep + '\n';
+  for (const [agent, model] of Object.entries(agentToModelMap)) {
+    agentToModelTable += ' ' + agent.padEnd(agentWidth) + ' │ ' + model.padEnd(modelWidth) + '\n';
+  }
+  return agentToModelTable;
+}
+
+/**
+ * Returns a mapping from agent to model for the given model profile.
+ *
+ * @param {string} normalizedProfile - The normalized (lowercase and trimmed) profile name
+ * @returns {Object<string, string>} A mapping from agent to model for the given profile
+ */
+function getAgentToModelMapForProfile(normalizedProfile) {
+  const agentToModelMap = {};
+  for (const [agent, profileToModelMap] of Object.entries(MODEL_PROFILES)) {
+    agentToModelMap[agent] = profileToModelMap[normalizedProfile];
+  }
+  return agentToModelMap;
+}
+
+module.exports = {
+  MODEL_PROFILES,
+  VALID_PROFILES,
+  formatAgentToModelMapAsTable,
+  getAgentToModelMapForProfile,
+};

package/cap/bin/lib/monorepo-context.cjs

@@ -0,0 +1,226 @@
+// @cap-context Monorepo context resolver -- assembles per-app planning paths and agent context for scoped operations
+// @cap-decision Separate module from workspace-detector to keep detection (read-only) separate from planning structure (write operations)
+// @cap-constraint Zero external dependencies -- uses only Node.js built-ins (fs, path)
+// @cap-ref(ref:AC-3) Each scoped app gets its own .planning/ directory with independent CODE-INVENTORY.md, PRD.md, and FEATURES.md
+// @cap-ref(ref:AC-7) Root .planning/ holds global decisions; app .planning/ holds app-specific work
+// @cap-pattern Two-level planning: root .planning/ for global context, app-path/.planning/ for scoped work
+
+'use strict';
+
+// @cap-feature(feature:F-012) Monorepo Support — per-app planning context resolution
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// @cap-api resolveAppPlanningDir(rootPath, appRelativePath) -- returns absolute path to app-scoped .planning/ directory
+
+/**
+ * @typedef {Object} MonorepoContext
+ * @property {string} rootPlanningDir - Absolute path to root .planning/
+ * @property {string} appPlanningDir - Absolute path to app-scoped .planning/
+ * @property {string} appRoot - Absolute path to the scoped app directory
+ * @property {string} appName - Name of the scoped app
+ * @property {string[]} manifestPaths - Paths to relevant package manifests for this app
+ * @property {Object} globalContext - Parsed global planning docs (lightweight refs)
+ */
+
+/**
+ * Resolve the .planning/ directory for an app-scoped operation.
+ *
+ * @param {string} rootPath - Monorepo root
+ * @param {string} appRelativePath - Relative path to the app (e.g., 'apps/dashboard')
+ * @returns {string} Absolute path to app .planning/ directory
+ */
+function resolveAppPlanningDir(rootPath, appRelativePath) {
+  return path.join(rootPath, appRelativePath, '.planning');
+}
+
+/**
+ * Initialize the per-app .planning/ directory structure.
+ * Creates the directory and placeholder files mirroring root .planning/.
+ *
+ * @param {string} rootPath - Monorepo root
+ * @param {string} appRelativePath - Relative path to the app
+ * @param {Object} [options]
+ * @param {string} [options.appName] - Display name for headers
+ * @returns {string} Path to created .planning/ directory
+ */
+function initAppPlanning(rootPath, appRelativePath, options) {
+  options = options || {};
+  const appPlanningDir = resolveAppPlanningDir(rootPath, appRelativePath);
+  const appName = options.appName || path.basename(appRelativePath);
+
+  fs.mkdirSync(appPlanningDir, { recursive: true });
+  fs.mkdirSync(path.join(appPlanningDir, 'prototype'), { recursive: true });
+
+  // @cap-decision Create stub PRD.md and FEATURES.md in app .planning/ -- agents expect these files to exist
+  const prdPath = path.join(appPlanningDir, 'PRD.md');
+  if (!fs.existsSync(prdPath)) {
+    fs.writeFileSync(prdPath, `# ${appName} -- PRD\n\nApp-scoped PRD. Generated by monorepo-init.\n`, 'utf-8');
+  }
+
+  const featuresPath = path.join(appPlanningDir, 'FEATURES.md');
+  if (!fs.existsSync(featuresPath)) {
+    fs.writeFileSync(featuresPath, `# ${appName} -- Feature Map\n\nAuto-generated. Run extract-plan --app ${appRelativePath} to populate.\n`, 'utf-8');
+  }
+
+  // Create prototype/CODE-INVENTORY.md stub
+  const codeInventoryPath = path.join(appPlanningDir, 'prototype', 'CODE-INVENTORY.md');
+  if (!fs.existsSync(codeInventoryPath)) {
+    fs.writeFileSync(codeInventoryPath, `# CODE-INVENTORY.md\n\nRun /gsd:extract-plan --app ${appRelativePath} to populate.\n`, 'utf-8');
+  }
+
+  return appPlanningDir;
+}
+
+/**
+ * Build the full MonorepoContext for an app-scoped operation.
+ * This is the primary function agents consume to get focused context.
+ *
+ * @param {string} rootPath - Monorepo root
+ * @param {string} appRelativePath - Relative path to app
+ * @param {Object} [options]
+ * @param {string} [options.appName] - App display name
+ * @param {string[]} [options.appDependencies] - Package names this app depends on
+ * @returns {MonorepoContext}
+ */
+// @cap-api buildMonorepoContext(rootPath, appRelativePath, options) -- returns MonorepoContext with local + global planning refs
+function buildMonorepoContext(rootPath, appRelativePath, options) {
+  options = options || {};
+  const appAbsPath = path.join(rootPath, appRelativePath);
+  const appPlanningDir = resolveAppPlanningDir(rootPath, appRelativePath);
+  const rootPlanningDir = path.join(rootPath, '.planning');
+  const manifestsDir = path.join(rootPlanningDir, 'manifests');
+
+  const manifestPaths = resolveRelevantManifests(manifestsDir, appAbsPath, options.appDependencies || []);
+
+  // @cap-decision Load global context lazily -- only read file headers, not full content, to minimize token usage
+  const globalContext = loadGlobalContextRefs(rootPlanningDir);
+
+  return {
+    rootPlanningDir,
+    appPlanningDir,
+    appRoot: appAbsPath,
+    appName: options.appName || path.basename(appRelativePath),
+    manifestPaths,
+    globalContext,
+  };
+}
+
+/**
+ * Find package manifests relevant to a specific app based on its dependencies.
+ *
+ * @param {string} manifestsDir - Path to .planning/manifests/
+ * @param {string} appAbsPath - Absolute path to the app
+ * @param {string[]} knownDeps - Package names from workspace detection
+ * @returns {string[]} Paths to relevant manifest .md files
+ */
+function resolveRelevantManifests(manifestsDir, appAbsPath, knownDeps) {
+  // @cap-risk If app package.json is missing or malformed, no manifests are resolved -- agent gets no package context
+  const manifestPaths = [];
+
+  if (!fs.existsSync(manifestsDir)) return manifestPaths;
+
+  // Read app's package.json for its dependencies
+  const appPkgPath = path.join(appAbsPath, 'package.json');
+  let appDeps = [...knownDeps];
+
+  try {
+    const appPkg = JSON.parse(fs.readFileSync(appPkgPath, 'utf-8'));
+    const allDeps = { ...(appPkg.dependencies || {}), ...(appPkg.devDependencies || {}) };
+    for (const [name, version] of Object.entries(allDeps)) {
+      if (typeof version === 'string' && version.startsWith('workspace:')) {
+        if (!appDeps.includes(name)) appDeps.push(name);
+      }
+    }
+  } catch {
+    // No package.json or malformed -- use knownDeps only
+  }
+
+  // Match dependency names to manifest files
+  try {
+    const manifestFiles = fs.readdirSync(manifestsDir).filter(f => f.endsWith('.md'));
+    for (const file of manifestFiles) {
+      const baseName = file.replace('.md', '').replace(/__/g, '/');
+      // Check if any app dependency matches this manifest (with or without @ prefix)
+      const matches = appDeps.some(dep => {
+        const depNorm = dep.replace(/^@/, '');
+        return baseName === depNorm || baseName === dep;
+      });
+      if (matches) {
+        manifestPaths.push(path.join(manifestsDir, file));
+      }
+    }
+  } catch {
+    // manifestsDir not readable
+  }
+
+  return manifestPaths;
+}
+
+/**
+ * Load lightweight references from global .planning/ docs.
+ * Reads only headers and first paragraphs to minimize context size.
+ *
+ * @param {string} rootPlanningDir - Path to root .planning/
+ * @returns {Object} Global context references
+ */
+function loadGlobalContextRefs(rootPlanningDir) {
+  const refs = {
+    hasProject: false,
+    hasRoadmap: false,
+    hasRequirements: false,
+    projectSummary: null,
+  };
+
+  const projectPath = path.join(rootPlanningDir, 'PROJECT.md');
+  if (fs.existsSync(projectPath)) {
+    refs.hasProject = true;
+    try {
+      const content = fs.readFileSync(projectPath, 'utf-8');
+      // Extract first 5 lines as summary
+      refs.projectSummary = content.split('\n').slice(0, 5).join('\n');
+    } catch {
+      // Ignore
+    }
+  }
+
+  refs.hasRoadmap = fs.existsSync(path.join(rootPlanningDir, 'ROADMAP.md'));
+  refs.hasRequirements = fs.existsSync(path.join(rootPlanningDir, 'REQUIREMENTS.md'));
+
+  return refs;
+}
+
+/**
+ * Modify extract-tags scan path to scope to an app directory.
+ * Used by the --app flag in cap-tools.cjs extract-tags case.
+ *
+ * @param {string} rootPath - Monorepo root
+ * @param {string} appRelativePath - App-scoped path
+ * @param {Object} originalOpts - Original extract-tags options
+ * @returns {Object} Modified options with scoped targetPath and outputFile
+ */
+// @cap-api scopeExtractTags(rootPath, appRelativePath, originalOpts) -- returns modified options for app-scoped tag extraction
+function scopeExtractTags(rootPath, appRelativePath, originalOpts) {
+  const appAbsPath = path.join(rootPath, appRelativePath);
+  const appPlanningDir = resolveAppPlanningDir(rootPath, appRelativePath);
+
+  return {
+    ...originalOpts,
+    // Override target path to scan only the app directory
+    targetPath: appAbsPath,
+    // Write output to app-scoped .planning/prototype/
+    outputFile: originalOpts.outputFile
+      ? path.join(appPlanningDir, 'prototype', path.basename(originalOpts.outputFile))
+      : originalOpts.outputFile,
+  };
+}
+
+module.exports = {
+  resolveAppPlanningDir,
+  initAppPlanning,
+  buildMonorepoContext,
+  resolveRelevantManifests,
+  loadGlobalContextRefs,
+  scopeExtractTags,
+};