eai-cli 0.0.0-bootstrap.0

package/resources/gofer/memory/diagrams/module-dependencies.mmd

@@ -0,0 +1,264 @@
+```mermaid
+graph TB
+    subgraph "BEFORE: Monolithic Architecture (Technical Debt)"
+        Extension1["extension.ts<br/>1200 LOC<br/>❌ God Object"]
+        Migrator1["goferMigrator.ts<br/>2499 LOC<br/>❌ God Object"]
+
+        Extension1 --> Migrator1
+        Extension1 --> VSCode1[VSCode API]
+        Migrator1 --> VSCode1
+        Migrator1 --> FS1[File System]
+
+        style Extension1 fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px
+        style Migrator1 fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px
+    end
+
+    subgraph "AFTER: Modular Architecture (Refactored)"
+        subgraph "Core Infrastructure (Phase 1)"
+            Container["DI Container<br/>87 LOC"]
+            Logger["Logger Service<br/>147 LOC"]
+
+            Container -.->|registers| Logger
+        end
+
+        subgraph "Extension Services (Phase 3)"
+            Extension2["extension.ts<br/>~800 LOC<br/>✅ Orchestrator"]
+            Disposal["DisposalService<br/>~200 LOC"]
+            Events["EventHandlers<br/>~200 LOC"]
+            Init["InitializationService<br/>~300 LOC"]
+            Commands["CommandRegistry<br/>~250 LOC"]
+            State["StateManager<br/>~150 LOC"]
+        end
+
+        subgraph "Migration Services (Phase 4)"
+            Migrator2["goferMigrator.ts<br/>467 LOC<br/>✅ Facade"]
+            Version["VersionDetector<br/>247 LOC"]
+            Upgrade["UpgradeService<br/>437 LOC"]
+            Resource["ResourceSyncer<br/>496 LOC"]
+            Path["PathMigrator<br/>332 LOC"]
+        end
+
+        %% DI Container relationships
+        Container -.->|resolves| Disposal
+        Container -.->|resolves| Events
+        Container -.->|resolves| Init
+        Container -.->|resolves| Commands
+        Container -.->|resolves| State
+        Container -.->|resolves| Version
+        Container -.->|resolves| Upgrade
+        Container -.->|resolves| Resource
+        Container -.->|resolves| Path
+
+        %% Extension service dependencies
+        Extension2 --> Container
+        Extension2 --> Init
+        Extension2 --> State
+        Extension2 --> VSCode2[VSCode API]
+
+        Init --> Commands
+        Init --> Events
+        Disposal --> Logger
+        Events --> Logger
+        Init --> Logger
+        Commands --> Logger
+        State --> Logger
+
+        %% Migration service dependencies
+        Migrator2 --> Container
+        Migrator2 --> Version
+        Migrator2 --> Upgrade
+        Migrator2 --> Resource
+        Migrator2 --> Path
+
+        Upgrade --> Logger
+        Upgrade --> Version
+        Version --> Logger
+        Resource --> Logger
+        Resource --> FS2[File System]
+        Path --> Logger
+        Path --> FS2
+
+        %% External dependencies
+        Resource --> VSCode2
+        Path --> VSCode2
+
+        style Extension2 fill:#51cf66,stroke:#2f9e44,stroke-width:3px
+        style Migrator2 fill:#51cf66,stroke:#2f9e44,stroke-width:3px
+        style Logger fill:#339af0,stroke:#1864ab,stroke-width:2px
+        style Container fill:#339af0,stroke:#1864ab,stroke-width:2px
+    end
+```
+
+# Module Dependencies Diagram
+
+This diagram shows the architecture transformation from monolithic God objects
+to modular services.
+
+## Metrics Comparison
+
+| Metric                   | Before (Monolithic) | After (Modular) | Improvement    |
+| ------------------------ | ------------------- | --------------- | -------------- |
+| **extension.ts LOC**     | 1200                | ~800            | -33% (400 LOC) |
+| **goferMigrator.ts LOC** | 2499                | 467             | -81% (2032 LOC) |
+| **Total God object LOC** | 3699                | 1267            | -66% (2432 LOC) |
+| **Service count**        | 2 (monoliths)       | 12 (focused)    | +10 services   |
+| **Max service LOC**      | 2499                | 496             | -80%           |
+| **Testable units**       | 2                   | 12              | 6x increase    |
+
+## Architecture Principles
+
+### Before: Monolithic (Anti-Patterns)
+
+❌ **God Objects**: Single files with 1000+ LOC and 20+ responsibilities
+
+- `extension.ts`: Initialization + Events + Commands + Disposal
+- `goferMigrator.ts`: Detection + Orchestration + Resources + Paths
+
+❌ **High Coupling**: Direct instantiation with `new`, global state
+
+❌ **Low Cohesion**: Unrelated functions in same file
+
+❌ **Difficult Testing**: Too many mocks needed, can't test parts in isolation
+
+### After: Modular (Best Practices)
+
+✅ **Single Responsibility**: Each service has one focused purpose
+
+- `VersionDetector`: Only format detection
+- `UpgradeService`: Only orchestration
+- `ResourceSyncer`: Only file operations
+- `PathMigrator`: Only path migration
+
+✅ **Dependency Injection**: Container manages lifecycles, explicit dependencies
+
+✅ **Facade Pattern**: `extension.ts` and `goferMigrator.ts` become thin
+orchestrators
+
+✅ **Testability**: Services tested independently with mocked dependencies
+
+## Service Responsibilities
+
+### Core Infrastructure (Phase 1)
+
+| Service   | Responsibility                | LOC | Dependencies |
+| --------- | ----------------------------- | --- | ------------ |
+| Container | DI service registration       | 87  | TSyringe     |
+| Logger    | Structured logging            | 147 | VSCode API   |
+
+### Extension Services (Phase 3)
+
+| Service        | Responsibility                  | LOC  | Dependencies         |
+| -------------- | ------------------------------- | ---- | -------------------- |
+| extension.ts   | Orchestrates activation         | ~800 | All services         |
+| Disposal       | Resource cleanup                | ~200 | Logger               |
+| EventHandlers  | Workspace event listeners       | ~200 | Logger               |
+| Init           | Workspace initialization        | ~300 | Logger, Commands     |
+| CommandRegistry| Command registration            | ~250 | Logger               |
+| StateManager   | Global state management         | ~150 | Logger               |
+
+### Migration Services (Phase 4)
+
+| Service          | Responsibility                  | LOC  | Dependencies         |
+| ---------------- | ------------------------------- | ---- | -------------------- |
+| goferMigrator.ts | Facade for migration services   | 467  | All migration svcs   |
+| VersionDetector  | Format detection                | 247  | Logger               |
+| UpgradeService   | Upgrade orchestration           | 437  | Logger, Version      |
+| ResourceSyncer   | File/resource sync              | 496  | Logger               |
+| PathMigrator     | Path reference migration        | 332  | Logger               |
+
+## Dependency Layers
+
+### Layer 1: Foundation
+
+- **Container**: Manages all service lifecycles
+- **Logger**: Used by all services (zero dependencies)
+
+### Layer 2: Core Services
+
+- **StateManager**: Maintains extension state (depends: Logger)
+- **DisposalService**: Cleans up resources (depends: Logger)
+
+### Layer 3: Feature Services
+
+- **Extension Services**: EventHandlers, InitializationService, CommandRegistry
+  (depend: Logger)
+- **Migration Services**: VersionDetector, UpgradeService, ResourceSyncer,
+  PathMigrator (depend: Logger, VersionDetector)
+
+### Layer 4: Facades
+
+- **extension.ts**: Orchestrates extension lifecycle
+- **goferMigrator.ts**: Orchestrates migration operations
+
+## Benefits of Refactoring
+
+### Code Quality
+
+- ✅ **Reduced complexity**: Max 496 LOC per file vs. 2499 LOC
+- ✅ **Improved cohesion**: Services have single, clear purpose
+- ✅ **Better naming**: Service names describe responsibility
+
+### Maintainability
+
+- ✅ **Easier navigation**: Find code by service (e.g., "path migration" →
+  `PathMigrator.ts`)
+- ✅ **Isolated changes**: Update one service without touching others
+- ✅ **Reduced merge conflicts**: Team works on different services
+
+### Testing
+
+- ✅ **Unit testable**: Mock dependencies via DI container
+- ✅ **Integration testable**: Test service interactions
+- ✅ **Faster tests**: Test one service at a time (not entire God object)
+
+### Development Velocity
+
+- ✅ **Parallel development**: Different developers on different services
+- ✅ **Faster onboarding**: Understand one 300 LOC service vs. 2500 LOC file
+- ✅ **Easier reviews**: 200-500 LOC PRs vs. 1000+ LOC changes
+
+## Anti-Patterns Eliminated
+
+### Before
+
+1. **Blob/God Object**: 2499 LOC monolith
+2. **Lava Flow**: Unclear which code is used
+3. **Spaghetti Code**: Tangled control flow
+4. **Golden Hammer**: Everything in one file
+
+### After
+
+1. **Single Responsibility**: Each service focused
+2. **Dependency Injection**: Explicit dependencies
+3. **Facade Pattern**: Thin orchestrators
+4. **Service Layer**: Clean separation of concerns
+
+## Future Phases
+
+### Phase 2: Cache Services (Pending)
+
+Will add:
+
+- `SpecCache` (spec file caching)
+- `MemoryCache` (memory indexing)
+
+Both follow same pattern: <600 LOC, depend on Logger, registered in Container.
+
+### Future Extraction Opportunities
+
+If any service grows >500 LOC:
+
+- Extract sub-services using same pattern
+- Maintain <600 LOC limit per file
+- Apply facade pattern if needed
+
+## Related ADRs
+
+- **ADR-001**: DI Framework (TSyringe)
+- **ADR-002**: Module Extraction Strategy (Phased with Facades)
+- **ADR-003**: Error Handling (Logger service)
+
+## Related Tasks
+
+- **Phase 3**: T020-T025 (extension.ts refactoring)
+- **Phase 4**: T026-T030 (goferMigrator.ts refactoring)

package/resources/gofer/memory/gofer-model-policy.yaml

@@ -0,0 +1,97 @@
+# Gofer model policy for this repository.
+#
+# This repo copy is user-owned. `gofer:bootstrap-workspace` and VS Code
+# `gofer.initialize` create it when missing, but should not overwrite local
+# edits. See `.specify/templates/gofer-model-policy.yaml` for the shipped
+# default.
+#
+# Last verified against public provider docs: 2026-05-30.
+version: 1
+lastVerified: "2026-05-30"
+profile: balanced
+
+principles:
+  - Use the cheapest capable model first for repetitive scouting, extraction, and summarization.
+  - Use the default workhorse model for normal implementation, synthesis, and validation.
+  - Use the best available model for security, architecture, release-critical review, or repeated failure.
+  - Use provider prompt/context caching only for stable, non-secret prefixes.
+  - Compact or checkpoint after large research, planning, implementation, and validation bursts.
+
+contextPolicy:
+  healthyBelowPercent: 40
+  summarizeAtPercent: 55
+  compactAtPercent: 70
+  checkpointAtPercent: 85
+  durableArtifact: .specify/specs/{feature}/context-bundle.md
+
+surfaces:
+  claude:
+    simple:
+      model: claude-haiku-4-5
+      claudeCodeAlias: haiku
+      contextWindowTokens: 200000
+      useFor: scouting, extraction, summarization, low-risk helpers
+    medium:
+      model: claude-sonnet-4-6
+      claudeCodeAlias: sonnet
+      contextWindowTokens: 1000000
+      useFor: default implementation, synthesis, validation, everyday coding
+    hard:
+      model: claude-opus-4-8
+      claudeCodeAlias: opus
+      contextWindowTokens: 1000000
+      useFor: hardest bugs, security review, architecture arbitration, release-critical validation
+  codex:
+    simple:
+      model: gpt-5.4-mini
+      reasoningEffort: low
+      contextWindowTokens: 400000
+      useFor: simple coding, focused edits, routine test fixes
+    mechanical:
+      model: gpt-5.4-nano
+      reasoningEffort: low
+      contextWindowTokens: 400000
+      useFor: locate, classify, summarize, transform text
+    medium:
+      model: gpt-5.4
+      reasoningEffort: medium
+      contextWindowTokens: 1000000
+      useFor: default planning, implementation, research synthesis
+    hard:
+      model: gpt-5.3-codex
+      reasoningEffort: high
+      contextWindowTokens: 400000
+      useFor: agentic terminal coding, tool-heavy debugging, code review
+    arbiter:
+      model: gpt-5.5
+      reasoningEffort: high
+      contextWindowTokens: 1050000
+      useFor: broad frontier reasoning, complex architecture, final arbitration
+  gemini:
+    simple:
+      model: gemini-3.1-flash-lite
+      contextWindowTokens: 1000000
+      useFor: cheap large-context scans, summarization, extraction
+    medium:
+      model: gemini-3-flash-preview
+      contextWindowTokens: 1000000
+      useFor: default research and broad synthesis when cost matters
+    hard:
+      model: gemini-3.1-pro-preview
+      contextWindowTokens: 1000000
+      useFor: large-context architecture, cross-repo reasoning, high-risk research
+    highThroughputCoding:
+      model: gemini-3.5-flash
+      contextWindowTokens: 1000000
+      useFor: fast tool/coding workflows when account pricing makes it worthwhile
+  copilot:
+    simple:
+      model: Auto
+      useFor: default Copilot Chat, routine coding, completion, and quick fixes
+    medium:
+      model: Auto
+      useFor: normal Gofer stage prompts and workspace questions
+    hard:
+      model: "Best available in picker: GPT-5.3-Codex, GPT-5.5, Claude Opus, or Gemini Pro"
+      useFor: explicit hard review, security, architecture, or release gates
+    note: Copilot model availability depends on plan, organization policy, client, and feature surface.

package/resources/gofer/memory/lessons.md

@@ -0,0 +1,46 @@
+# Gofer Lessons Learned
+
+Cross-cutting lessons captured from incidents, corrections, and
+post-implementation reviews. Review at session start; update after any
+correction.
+
+---
+
+## 2026-04-25: Codex skill-budget hygiene
+
+**Incident**: Codex CLI logged `Exceeded skills context budget of 2%` and
+dropped descriptions of all installed skills. Investigation revealed 11
+duplicate Gofer skill bundles (one per Anthropic-tenant) plus 5 system skills,
+totaling ~30KB of skill descriptions across 181 SKILL.md files.
+
+**Root cause**: Codex preloads ~2% of context for skill name+description text.
+Over-budget triggers a global drop, not per-bundle eviction. Multiple tenanted
+copies multiplied the description footprint.
+
+**Fix**:
+
+1. Disabled 176 redundant `[[skills.config]] enabled = false` entries in
+   `~/.codex/config.toml` (backup: `.bak.2026-04-25`).
+2. Shipped `gofer codex doctor` (read-only) to detect this proactively.
+3. Source-of-truth generator enforces ≤140-char descriptions per stage and ≤2KB
+   cumulative budget.
+4. Flat non-tenanted layout: `.agents/skills/gofer/<stage>/SKILL.md` (one bundle
+   per stage, no per-tenant duplication).
+
+**Lessons**:
+
+- The official Codex disable knob is per-skill
+  `[[skills.config]] enabled = false`, NOT a budget percentage. The fictional
+  `skills_context_budget_percent` key DOES NOT EXIST.
+- Codex discovers `.agents/skills/`, not `.claude/skills/`. They are separate
+  distribution paths.
+- Read-only diagnostics (`gofer codex doctor`) are safer than auto-remediation:
+  never silently mutate user config.
+- Description discipline matters: 16 stages × 128 bytes/desc = 2KB headroom; one
+  verbose description blows the entire budget for everyone.
+
+**References**:
+
+- Spec FR-006, FR-008, FR-009, FR-011 (negative)
+- ADR-001 (Codex skill discovery path)
+- `.specify/scripts/node/codex-doctor.mjs`

package/resources/gofer/node-scripts/canonical-descriptions.mjs

@@ -0,0 +1,86 @@
+/**
+ * canonical-descriptions.mjs
+ * Canonical descriptions for all Gofer pipeline, utility, and helper commands
+ * that participate in the Codex skill-budget inventory.
+ * Each description must be ≤140 chars and the cumulative UTF-8 byte total
+ * must not exceed 2048 bytes (Codex skill-budget constraint).
+ */
+
+export const CANONICAL_DESCRIPTIONS = {
+  '0_gofer_start':
+    'Define the business problem Gofer should solve.',
+  '0a_problem_validation':
+    'Validate the problem with 5 Whys and stakeholder mapping.',
+  '1_gofer_research':
+    'Research the codebase, integrations, and technology landscape.',
+  '2_gofer_specify':
+    'Generate a feature spec from research and approved review.',
+  '3_gofer_plan':
+    'Create the technical plan, architecture, data model, and contracts.',
+  '4_gofer_tasks':
+    'Break the plan into dependency-ordered, parallel tasks.',
+  '5_gofer_implement':
+    'Execute tasks phase by phase with feedback and review.',
+  '6_gofer_validate':
+    'Validate the work with scoring, blast-radius analysis, and review.',
+  '7_gofer_save':
+    'Save session state for later resumption.',
+  '7a_stakeholder_comms':
+    'Generate release notes, demos, and change briefs for stakeholders.',
+  '8_gofer_branding':
+    'Brand Gofer templates and stakeholder documents.',
+  '9_gofer_tests':
+    'Generate tests from four perspectives for a target component.',
+  '10_gofer_cloud':
+    'Deploy and configure Gofer cloud integration.',
+  gofer_constitution:
+    'Create or update the project constitution.',
+  gofer_hydrate:
+    'Reverse-engineer a specification from existing code.',
+  'gofer:check-workspace':
+    'Check whether the repo scaffold is missing or stale.',
+  'gofer:bootstrap-workspace':
+    'Create or update the repo-owned Gofer scaffold.',
+  'gofer:eai-first-run':
+    'Check EAI CLI, login, tenant, template, and Gofer readiness.',
+  'gofer:vocabulary':
+    'Extract domain terms into a canonical glossary.',
+  'gofer:diagnose':
+    'Run a structured reproduce-minimize-instrument-fix loop.',
+  'gofer:tdd':
+    'Guide a red-green-refactor loop tied to acceptance criteria.',
+  'gofer:spec-summary':
+    'Generate a business summary of feature value and scope.',
+  'gofer:zoom-out':
+    'Show how the current feature fits broader system boundaries.',
+};
+
+/**
+ * Validates that all descriptions satisfy the Codex budget constraints:
+ * - Each description is ≤140 chars
+ * - Cumulative UTF-8 byte total ≤2048 bytes
+ *
+ * @throws {Error} if any constraint is violated
+ */
+export function validateDescriptions() {
+  const entries = Object.entries(CANONICAL_DESCRIPTIONS);
+  let totalBytes = 0;
+
+  for (const [name, description] of entries) {
+    if (description.length > 140) {
+      throw new Error(
+        `Description for '${name}' exceeds 140 chars: ${description.length} chars`
+      );
+    }
+    const bytes = Buffer.byteLength(description, 'utf8');
+    totalBytes += bytes;
+  }
+
+  if (totalBytes > 2048) {
+    throw new Error(
+      `Cumulative UTF-8 byte total exceeds 2048 bytes: ${totalBytes} bytes`
+    );
+  }
+
+  return { count: entries.length, totalBytes };
+}

package/resources/gofer/node-scripts/check-version-alignment.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DEFAULT_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+function parseArgs(argv) {
+  const args = { root: DEFAULT_ROOT, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--root') {
+      args.root = path.resolve(argv[index + 1] ?? '');
+      index += 1;
+    } else if (arg === '--json') {
+      args.json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      args.help = true;
+    }
+  }
+  return args;
+}
+
+function readJson(root, relativePath) {
+  const fullPath = path.join(root, relativePath);
+  const content = fs.readFileSync(fullPath, 'utf8');
+  return JSON.parse(content);
+}
+
+function readText(root, relativePath) {
+  return fs.readFileSync(path.join(root, relativePath), 'utf8').trim();
+}
+
+function collectVersions(root) {
+  const codexPluginManifest = readJson(root, '.codex-plugin/plugin.json');
+  const releaseAssetVersion =
+    /eai-gofer-agent-plugin-([^/]+)\.zip$/.exec(
+      codexPluginManifest.gofer?.releaseAsset ?? ''
+    )?.[1] ?? 'missing';
+
+  return [
+    {
+      name: 'root package',
+      path: 'package.json',
+      version: readJson(root, 'package.json').version,
+    },
+    {
+      name: 'root package lock',
+      path: 'package-lock.json',
+      version: readJson(root, 'package-lock.json').version,
+    },
+    {
+      name: 'extension package',
+      path: 'extension/package.json',
+      version: readJson(root, 'extension/package.json').version,
+    },
+    {
+      name: 'extension package lock',
+      path: 'extension/package-lock.json',
+      version: readJson(root, 'extension/package-lock.json').version,
+    },
+    {
+      name: 'Claude plugin manifest',
+      path: '.claude-plugin/plugin.json',
+      version: readJson(root, '.claude-plugin/plugin.json').version,
+    },
+    {
+      name: 'Codex plugin manifest',
+      path: '.codex-plugin/plugin.json',
+      version: codexPluginManifest.version,
+    },
+    {
+      name: 'Codex plugin release asset',
+      path: '.codex-plugin/plugin.json#gofer.releaseAsset',
+      version: releaseAssetVersion,
+    },
+    {
+      name: 'workspace version marker',
+      path: '.specify/.gofer-version',
+      version: readText(root, '.specify/.gofer-version'),
+    },
+  ];
+}
+
+function checkVersionAlignment(root) {
+  const entries = collectVersions(root);
+  const uniqueVersions = [...new Set(entries.map((entry) => entry.version))].sort();
+  const aligned = uniqueVersions.length === 1;
+  return {
+    aligned,
+    expectedVersion: aligned ? uniqueVersions[0] : undefined,
+    versions: entries,
+    mismatches: aligned ? [] : entries,
+  };
+}
+
+function formatMarkdown(result) {
+  const lines = ['# Gofer Version Alignment', ''];
+  lines.push(`Status: ${result.aligned ? 'PASS' : 'FAIL'}`);
+  if (result.expectedVersion) {
+    lines.push(`Version: ${result.expectedVersion}`);
+  }
+  lines.push('', '| Source | Path | Version |', '| --- | --- | --- |');
+  for (const entry of result.versions) {
+    lines.push(`| ${entry.name} | \`${entry.path}\` | \`${entry.version ?? 'missing'}\` |`);
+  }
+  return lines.join('\n');
+}
+
+if (__filename === path.resolve(process.argv[1] ?? '')) {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(`Usage: node .specify/scripts/node/check-version-alignment.mjs [--root <path>] [--json]
+
+Checks that root package, extension package, plugin manifests, and .gofer-version
+all carry the same Gofer release version.`);
+    process.exit(0);
+  }
+
+  const result = checkVersionAlignment(args.root);
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatMarkdown(result));
+  }
+  process.exit(result.aligned ? 0 : 1);
+}
+
+export { checkVersionAlignment, collectVersions, formatMarkdown, parseArgs };