eai-cli 0.0.0-bootstrap.0

package/resources/gofer/memory/constitution.md

@@ -0,0 +1,391 @@
+# Gofer Constitution
+
+## Core Principles
+
+### I. Test-Driven Development (NON-NEGOTIABLE)
+
+Tests MUST be written before implementation in all cases:
+
+- Write acceptance tests first based on spec requirements
+- Ensure tests FAIL before implementation begins
+- Implement minimum code to make tests pass (Red-Green-Refactor)
+- Integration tests required for all MCP tools, LSP methods, and agent
+  coordination
+- Contract tests mandatory for VSCode extension API, Language Server Protocol,
+  and Model Context Protocol boundaries
+
+**Rationale**: TDD ensures correctness, prevents regressions, and validates that
+specifications are implementable. The autonomous agent system depends on
+reliable tests to validate its own work.
+
+### II. MCP-First Architecture
+
+All AI assistant integration MUST use Model Context Protocol (MCP):
+
+- Expose functionality through well-defined MCP tools (naming: `gofer_<action>`)
+- Tools must be stateless, idempotent where possible, and return structured
+  results
+- File-based integration (`.claude-input.txt`/`.claude-output.txt`) is legacy
+  only
+- Tools respond in <100ms for sync operations, <1s for async operations
+- Each tool must validate inputs against schema before execution
+
+**Rationale**: MCP provides a standardized, maintainable interface for AI
+assistants. Native VSCode MCP support eliminates custom integration code.
+
+### III. Spec Kit Format Compliance
+
+All specifications MUST follow GitHub Spec Kit format:
+
+- YAML frontmatter with id, title, status, dates
+- Markdown body with structured sections (User Scenarios, Requirements,
+  Entities)
+- Task lists with dependency tracking:
+  `- [ ] #T001 Description (deps: T002, T003)`
+- Constitution validation before implementation
+- Migration tools provided for legacy JSON format
+
+**Rationale**: Standardized format enables automated parsing, validation, and
+coordination across multiple AI coding agents.
+
+### IV. Strict TypeScript & Code Quality
+
+All code must meet quality standards without exception:
+
+- TypeScript strict mode enabled (`noImplicitAny: true`,
+  `strictNullChecks: true`)
+- No `any` types - use proper types or `unknown` with type guards
+- Functions ≤300 lines, files ≤500 lines - decompose if exceeded
+- Cyclomatic complexity ≤10 per function
+- ES modules with `.js` extensions in imports (Node.js ESM compatibility)
+
+**Rationale**: Strict typing catches errors at compile time. Size limits enforce
+Single Responsibility Principle. Quality gates prevent technical debt.
+
+### V. Security by Default
+
+Security principles are non-negotiable at every layer:
+
+- **Authentication**: bcrypt/argon2 for passwords, JWT expiry <1 hour with
+  refresh rotation
+- **Input Validation**: Validate and sanitize all user input, path traversal
+  prevention
+- **Secrets**: Environment variables only, never committed to Git
+- **HTTPS**: All production traffic encrypted, HSTS enabled
+- **API Security**: Rate limiting (100 req/min), CSRF tokens on mutations
+
+**Rationale**: Autonomous systems must be secure by design. Security
+vulnerabilities in orchestration could enable arbitrary code execution.
+
+### VI. Performance Requirements
+
+All components must meet performance benchmarks:
+
+- **Extension**: Activation <500ms, tree view render <100ms
+- **Language Server**: Start <1s, spec loading <500ms for 100+ specs
+- **MCP Tools**: Response <100ms for queries, <1s for operations
+- **API**: Backend p95 <500ms, p99 <1000ms
+- **UI**: First Contentful Paint <1.5s, Time to Interactive <3.5s
+
+**Rationale**: Slow tools disrupt developer flow. Performance is a feature,
+especially for autonomous agents making rapid tool calls.
+
+### VII. 80% Test Coverage Minimum
+
+All new code must achieve 80% coverage across all metrics:
+
+- Line coverage ≥80%
+- Branch coverage ≥80%
+- Function coverage ≥80%
+- Critical paths (auth, orchestration, task execution) require 100% coverage
+- Coverage gates enforced in CI/CD pipeline
+
+**Rationale**: High coverage provides confidence in autonomous operation.
+Test-driven development naturally achieves these thresholds.
+
+### VIII. Minimal Necessary Changes
+
+All code modifications MUST be limited to what is directly required by the
+current task:
+
+- Only modify files listed in the task scope
+- Only make changes directly required by the task specification
+- Do not refactor surrounding code that is not part of the task
+- Do not add features, documentation, or tests beyond what is specified
+- Do not add error handling for scenarios that cannot occur in the current
+  context
+- Do not create abstractions for one-time operations
+- Three similar lines of code is better than a premature abstraction
+
+**Rationale**: Minimal changes reduce review burden, prevent regressions in
+unrelated code, and keep diffs focused. AI agents are especially prone to
+over-engineering and gold-plating — this principle provides an explicit check
+against scope creep.
+
+## Architecture Standards
+
+### Multi-Layered System
+
+Gofer consists of three coordinated components:
+
+**VSCode Extension** (`/extension/`):
+
+- Entry point: `extension/src/extension.ts` (auto-activates on `.specify/`
+  detection)
+- Manages UI (tree views, commands, progress panels)
+- Launches Language Server as child process
+- Auto-creates provider-neutral `.vscode/mcp.json` for VS Code/Copilot, Claude
+  Code, Codex, Gemini, and compatible agent apps
+
+**Language Server** (`/language-server/`):
+
+- Dual protocol: LSP (extension ↔ server) + MCP (agent app ↔ repo tools)
+- Exposes the current Gofer MCP tool set for specs, tasks, context health,
+  workspace check/bootstrap, pipeline state, validation, EAI error explanation,
+  and artifact reads
+- Loads specs from `.specify/specs/` using GitHub Spec Kit parser
+- Stateless design, all state in filesystem
+
+**Repo-Owned Pipeline Scripts** (`/.specify/scripts/`):
+
+- Remain the executable source of truth for Gofer stages, workspace checks,
+  bootstrap, hooks, context management, validation helpers, and release checks
+- Are called or explained by app plugins, skills, agents, and MCP tools instead
+  of duplicating workflow logic per host
+
+### Dependency Management
+
+- Three separate `package.json` files (root, extension, language-server)
+- Extension bundles Language Server via Webpack
+- Anthropic SDK for direct Claude API access
+- Playwright for autonomous testing
+
+### File Structure Conventions
+
+```text
+.specify/
+├── specs/
+│   └── ###-feature-name/
+│       ├── spec.md          # GitHub Spec Kit format
+│       ├── plan.md          # Technical implementation plan
+│       ├── tasks.md         # Task breakdown with dependencies
+│       └── contracts/       # API/interface definitions
+├── memory/
+│   └── constitution.md      # This file - project principles
+└── templates/
+    ├── spec-template.md
+    ├── plan-template.md
+    └── tasks-template.md
+```
+
+## Development Workflow
+
+### Task Execution Flow
+
+1. AI reads specs via `gofer_get_specs` MCP tool
+2. Gets next available task via `gofer_get_next_task` (checks dependencies)
+3. Marks task in-progress via `gofer_execute_task`
+4. Implements code following TDD (tests first, then implementation)
+5. Validates against constitution via `gofer_validate_code`
+6. Runs tests via `gofer_run_tests` (Playwright + unit tests)
+7. Updates status via `gofer_update_task_status` (completed/failed)
+8. Repeats - autonomous agents implement entire specs
+
+### Status Progression
+
+```text
+pending → in_progress → testing → completed
+                    ↓
+                  failed (max 3 attempts before human escalation)
+```
+
+### Quality Gates
+
+Before merging any code:
+
+- ✅ All tests pass (Vitest + Playwright)
+- ✅ 80%+ coverage threshold met
+- ✅ ESLint passes with zero warnings
+- ✅ TypeScript compiles with strict mode
+- ✅ Constitution validation passes
+- ✅ Spec acceptance criteria met
+
+## Governance
+
+### Amendment Process
+
+Constitution changes require:
+
+1. **Proposal**: Document change rationale in GitHub issue
+2. **Impact Analysis**: Identify affected templates, tests, and documentation
+3. **Version Bump**: MAJOR (breaking), MINOR (additive), PATCH (clarification)
+4. **Update Propagation**: Update templates, code validators, and test patterns
+5. **Migration Guide**: Provide upgrade path for existing specs
+6. **Approval**: Merge only after CI passes and review complete
+
+### Compliance Enforcement
+
+- EngineerAgent validates all code against these principles before completion
+- MCP tool `gofer_validate_code` programmatically checks compliance
+- CI/CD pipeline enforces coverage thresholds and linting rules
+- Extension warnings appear when specs don't follow GitHub Spec Kit format
+
+### Constitution Supersedes All
+
+In conflicts between this document and other practices:
+
+- Constitution wins - always
+- If constitution blocks legitimate work, amend the constitution first
+- Complexity violations require architectural approval with documented
+  justification
+
+### Guidance Documents
+
+- **Runtime Development**: See `.github/copilot-instructions.md` for AI
+  assistant patterns
+- **Testing**: See `docs/TESTING_GUIDE.md` for E2E and integration test setup
+- **Spec Kit**: See `.specify/templates/` for specification and task templates
+
+**Version**: 2.0.0 | **Ratified**: 2025-10-22 | **Last Amended**: 2025-10-22
+
+---
+
+## gofer:// URI Conventions (Feature 029 - Memory System v2)
+
+**Version Added**: 2.1.0 | **Feature**: 029-memory-system-v2
+
+The `gofer://` URI scheme provides uniform resource access across memory, specs,
+agents, and sessions without coupling code to filesystem paths.
+
+### URI Format
+
+```
+gofer://{scope}/{path}[#{fragment}]
+```
+
+### Scopes
+
+| Scope     | Filesystem Mapping                       | Example                                         |
+| --------- | ---------------------------------------- | ----------------------------------------------- |
+| `specs`   | `.specify/specs/{path}`                  | `gofer://specs/029-memory-system-v2/spec.md`    |
+| `memory`  | `.specify/memory/{path}`                 | `gofer://memory/core/task-context.md`           |
+| `agent`   | `.claude/agents/{path}`                  | `gofer://agent/validation-security.md`          |
+| `session` | `.specify/specs/{path}` (feature-scoped) | `gofer://session/029-memory-system-v2/tasks.md` |
+| `user`    | `~/.claude/projects/memory/{path}`       | `gofer://user/global-patterns.md`               |
+
+### Security Requirements
+
+- **Path traversal MUST be blocked**: `../` sequences and URL-encoded variants
+  (`%2e%2e`) are rejected
+- **Absolute paths MUST be rejected**: double-slash URIs creating `/path` are
+  blocked
+- **Scope MUST be validated**: only the 5 defined scopes are accepted
+- Implementation: `GoferURIResolver.resolve()` in
+  `extension/src/autonomous/memory/GoferURI.ts`
+
+### Usage by Sub-Agents
+
+Sub-agents reference resources via gofer:// URIs to enable location-independent
+access. When an agent receives `gofer://memory/core/task-context.md`, the
+extension resolves it to the current workspace path.
+
+**Example in agent prompt**:
+
+```
+Load the following contexts before starting:
+- Past patterns: gofer://memory/patterns/auth.md
+- Spec: gofer://specs/029-memory-system-v2/spec.md#requirements
+- Constitution: gofer://memory/constitution.md
+```
+
+### Glob Pattern Support
+
+Use `*` for single-level matching:
+
+```
+gofer://specs/029-*/research.md     # All 029 research docs
+gofer://agent/validation-*.md       # All validation agents
+```
+
+### Implementation
+
+- **Parser**: `parseGoferURI()` in `GoferURI.ts`
+- **Resolver**: `GoferURIResolver.resolve()` and `resolveGlob()`
+- **Integration**: `MemoryManager.loadByURI()` for memory scope
+
+---
+
+## Codex Skill Distribution (Hard Invariant 2)
+
+**Version Added**: 2.2.0 | **Feature**: 001-cli-innovations-visuals
+
+Gofer's Codex skill bundles emit to `.agents/skills/gofer/<stage>/SKILL.md`
+(flat, non-tenanted layout). This is the official Codex discovery path;
+`.claude/skills/` is NOT a Codex target. The two distribution paths are distinct
+and MUST NOT be conflated.
+
+### Constraints
+
+- **Per-skill description limit**: Each `SKILL.md` description MUST be ≤140
+  characters (UTF-8 bytes). The source-of-truth generator rejects emit when any
+  description exceeds this limit (FR-006).
+- **Cumulative description budget**: Cumulative description bytes across the 16
+  canonical Gofer stages MUST be ≤2048 bytes (≤2KB). Codex preloads ~2% of
+  context for skill name+description text; over-budget triggers a global drop of
+  ALL skill descriptions, not per-bundle eviction (NFR-004, SC-006).
+- **Per-CLI parity**: Numbered stages, utilities, and helper commands are
+  emitted to Claude, Codex, Gemini, Copilot, VS Code, GitHub prompts, agent
+  skills, and system skills unless their frontmatter explicitly says otherwise
+  (FR-007, SC-012).
+- **Flat tree**: Codex skill files emit at depth ≤2 from `.agents/skills/`; no
+  `<tenant>/<stage>/` nesting (FR-008).
+- **No fictional config keys**: The official Codex disable knob is per-skill
+  `[[skills.config]] enabled = false` in `~/.codex/config.toml`. There is NO
+  `skills_context_budget_percent` config key — do NOT invent one (FR-011,
+  SC-011).
+
+### Diagnostic — `gofer codex doctor`
+
+`gofer codex doctor` is a **read-only** diagnostic that scans `~/.codex/skills`,
+lists duplicate Gofer bundles, prints which paths exceed the 2% budget, and
+emits a paste-ready `[[skills.config]] enabled = false` block. It MUST NOT
+modify any file on disk (FR-009).
+
+---
+
+## Source-of-Truth (FR-001)
+
+**Version Added**: 2.2.0 | **Feature**: 001-cli-innovations-visuals
+
+All stage commands and control commands derive from canonical files at
+`.specify/commands/<stage>.md`. Each file has YAML frontmatter (name,
+description, surfaces, category, aliases, args) followed by a Markdown body.
+
+### Generator
+
+The generator at `.specify/scripts/node/generate-commands.mjs` emits to all
+configured CLI surfaces:
+
+- `.claude/commands/` (Claude Code)
+- `extension/resources/claude-prompts/` (Claude-mirror, VSCode)
+- `extension/resources/copilot-prompts/` (Copilot)
+- `.github/prompts/` (GitHub Prompts)
+- `.agents/skills/gofer/` (Codex)
+- `.gemini/commands/gofer/` (Gemini)
+- `.system/skills/` (system)
+
+### Anti-drift Guard
+
+Hand-edits to emitted files (`.claude/commands/`, `.github/prompts/`,
+`extension/resources/copilot-prompts/`, `.agents/skills/`, etc.) are detected by
+the generator and rejected without `--force-emit`. Always port the change back
+into the canonical `.specify/commands/<stage>.md` and re-run
+`npm run gofer:generate`.
+
+### Operator Commands
+
+| Command                        | Purpose                                                         |
+| ------------------------------ | --------------------------------------------------------------- |
+| `npm run gofer:generate`       | Regenerate all CLI surfaces from `.specify/commands/<stage>.md` |
+| `npm run gofer:codex-doctor`   | Read-only Codex skill-budget diagnostic                         |
+| `npm run gofer:mermaid-export` | Optional visual export via `mmdc` (NEVER uses `--no-sandbox`)   |

package/resources/gofer/memory/context-profiles.yaml

@@ -0,0 +1,74 @@
+# Context Profiles Configuration
+#
+# Defines context budget allocation for each Gofer pipeline stage.
+# Each stage has different priorities for research, memories, and code.
+#
+# Budget fractions must sum to <= 1.0 (remaining is for conversation)
+# observationWindow: number of turns to keep tool outputs before masking
+#
+# @see .specify/specs/011-context-health-recursive-memory/data-model.md
+
+version: '1.0'
+
+# Default profile used when stage is not specified
+default: implement
+
+profiles:
+  # /1_gofer_research - Deep codebase exploration
+  research:
+    stage: research
+    description: 'Research phase prioritizes broad codebase exploration'
+    researchBudget: 0.15 # Lower - we're generating research, not consuming it
+    memoryBudget: 0.20 # Medium - leverage prior knowledge
+    codeBudget: 0.40 # High - need to read lots of code
+    observationWindow: 15 # Keep more observations for exploration
+
+  # /2_gofer_specify - Feature specification creation
+  specify:
+    stage: specify
+    description: 'Specification phase balances research and requirements'
+    researchBudget: 0.30 # High - reference research.md
+    memoryBudget: 0.20 # Medium - prior decisions matter
+    codeBudget: 0.20 # Lower - focused on spec writing
+    observationWindow: 12
+
+  # /3_gofer_plan - Technical architecture design
+  plan:
+    stage: plan
+    description: 'Planning phase emphasizes architecture and contracts'
+    researchBudget: 0.25 # Medium-high - reference research
+    memoryBudget: 0.25 # High - architectural decisions
+    codeBudget: 0.25 # Medium - reference existing patterns
+    observationWindow: 10
+
+  # /4_gofer_tasks - Task breakdown generation
+  tasks:
+    stage: tasks
+    description: 'Task generation needs plan and spec context'
+    researchBudget: 0.20 # Medium - reference research
+    memoryBudget: 0.15 # Lower - focused on plan decomposition
+    codeBudget: 0.30 # High - understand implementation scope
+    observationWindow: 8
+
+  # /5_gofer_implement - Code implementation
+  implement:
+    stage: implement
+    description: 'Implementation maximizes code context for accuracy'
+    researchBudget: 0.10 # Lower - less exploration needed
+    memoryBudget: 0.15 # Medium - coding conventions
+    codeBudget: 0.45 # Maximum - active coding needs code context
+    observationWindow: 10 # Balance between context and recency
+
+  # /6_gofer_validate - Implementation verification
+  validate:
+    stage: validate
+    description: 'Validation compares implementation against spec'
+    researchBudget: 0.20 # Medium - reference requirements
+    memoryBudget: 0.15 # Lower - focused on verification
+    codeBudget: 0.35 # High - verify actual implementation
+    observationWindow: 12 # Keep test outputs longer
+
+# Budget allocation notes:
+# - Conversation takes remaining budget (1.0 - sum of budgets)
+# - Typical conversation allocation: 0.20-0.35 depending on stage
+# - Budgets can be adjusted per project in local config

package/resources/gofer/memory/decisions/000-use-adr-for-decisions.md

@@ -0,0 +1,67 @@
+---
+id: '000'
+title: Use Architectural Decision Records for Design Decisions
+status: accepted
+date: '2025-01-11'
+feature: project-wide
+---
+
+# Use Architectural Decision Records for Design Decisions
+
+## Context
+
+As Gofer evolves, design decisions are made during feature implementation.
+Without a systematic way to record these decisions:
+
+- Future contributors don't understand why things are built a certain way
+- The same debates are repeated across features
+- Inconsistent approaches emerge in different parts of the codebase
+- Knowledge is lost when context windows are cleared or sessions end
+
+## Decision
+
+We will use Architectural Decision Records (ADRs) stored in
+`.specify/memory/decisions/` to document significant design decisions.
+
+Each ADR follows a standard template with:
+
+- Frontmatter metadata (id, title, status, date, feature)
+- Context explaining the problem
+- Decision describing the solution
+- Consequences listing positive and negative outcomes
+- Alternatives considered with reasons for rejection
+
+## Consequences
+
+### Positive
+
+- Decisions are discoverable and searchable
+- New contributors can understand historical context
+- Consistent approach across all features
+- Enables learning from past decisions
+- Integrates with Gofer pipeline validation step
+
+### Negative
+
+- Adds overhead to document decisions
+- May create too many records if threshold is too low
+- Requires maintenance as decisions become outdated
+
+## Alternatives Considered
+
+1. **Inline code comments**
+   - Description: Document decisions in the code itself
+   - Rejected because: Hard to discover, doesn't capture alternatives considered
+
+2. **Feature-specific research.md only**
+   - Description: Keep all decisions in feature research files
+   - Rejected because: Project-wide decisions need a central location
+
+3. **CLAUDE.md only**
+   - Description: Put all decisions in CLAUDE.md
+   - Rejected because: Would make CLAUDE.md too large and unfocused
+
+## References
+
+- [ADR GitHub organization](https://adr.github.io/)
+- Gofer pipeline validation step (6_gofer_validate.md)