@entelligentsia/forgecli 0.10.1 → 0.11.2

package/dist/forge-payload/meta/skill-recommendations.md

@@ -0,0 +1,154 @@
+# Forge Skill Recommendations
+
+Maps discovered stack components to verified Claude Code marketplace skills.
+Used during `forge:init` (Phase 2) and `forge:health` to recommend skills
+that complement Forge's project-specific knowledge.
+
+## Skill Sources
+
+Skills come from two locations — both are checked by `tools/list-skills.js`:
+
+| Source | Location | Install mechanism |
+|---|---|---|
+| Marketplace plugin | `~/.claude/plugins/installed_plugins.json` | `/plugin install <name>@<marketplace>` |
+| Personal skill | `~/.claude/skills/<name>/SKILL.md` | Manual — place SKILL.md in directory |
+
+Marketplace install format: `/plugin install <skill-name>@<marketplace>`
+
+Personal skills cannot be installed via `/plugin install`. If a recommended personal
+skill is not present, surface it in the health report with its source noted as "personal skill".
+
+---
+
+## Why This Matters
+
+Forge generates project-specific context: your entities, auth patterns,
+business rules, conventions. Marketplace skills provide universal technique
+knowledge: LSP intelligence for your language, frontend design patterns, etc.
+A Forge-generated persona that invokes a relevant skill gets both layers —
+project knowledge AND technique depth — without duplication.
+
+---
+
+## Language Servers (LSP)
+
+High-confidence for any project using the matched language. LSP skills give
+agents go-to-definition, find-references, static analysis, and real-time
+diagnostics, dramatically reducing hallucinated API usage.
+
+| If stack language includes | Skill | Marketplace | Install |
+|---|---|---|---|
+| TypeScript, JavaScript | `typescript-lsp` | claude-plugins-official | `/plugin install typescript-lsp@claude-plugins-official` |
+| Python | `pyright-lsp` | claude-plugins-official | `/plugin install pyright-lsp@claude-plugins-official` |
+| Ruby | `ruby-lsp` | claude-plugins-official | `/plugin install ruby-lsp@claude-plugins-official` |
+| Go | `gopls-lsp` | claude-plugins-official | `/plugin install gopls-lsp@claude-plugins-official` |
+| Rust | `rust-analyzer-lsp` | claude-plugins-official | `/plugin install rust-analyzer-lsp@claude-plugins-official` |
+| Java | `jdtls-lsp` | claude-plugins-official | `/plugin install jdtls-lsp@claude-plugins-official` |
+| Kotlin | `kotlin-lsp` | claude-plugins-official | `/plugin install kotlin-lsp@claude-plugins-official` |
+| C# / .NET | `csharp-lsp` | claude-plugins-official | `/plugin install csharp-lsp@claude-plugins-official` |
+| C, C++ | `clangd-lsp` | claude-plugins-official | `/plugin install clangd-lsp@claude-plugins-official` |
+| PHP | `php-lsp` | claude-plugins-official | `/plugin install php-lsp@claude-plugins-official` |
+| Swift, iOS | `swift-lsp` | claude-plugins-official | `/plugin install swift-lsp@claude-plugins-official` |
+| Lua | `lua-lsp` | claude-plugins-official | `/plugin install lua-lsp@claude-plugins-official` |
+
+---
+
+## Frontend & UI
+
+| If stack contains | Skill | Source | Confidence | Why |
+|---|---|---|---|---|
+| Any web UI, React, Vue, Svelte | `frontend-design` | `claude-plugins-official` | High | Production-grade UI, distinctive design, avoids generic AI aesthetics |
+| Vue, Nuxt, Pinia, Vue Router | `vue-best-practices` | personal (`~/.claude/skills/`) | High | Composition API, `<script setup>`, TypeScript, SSR, Volar, vue-tsc |
+
+---
+
+## 3D Graphics & XR
+
+| If stack contains | Skill | Marketplace | Why |
+|---|---|---|---|
+| Three.js | `threejs-skills` | agentic-skills | 10 skills: scene, geometry, materials, lighting, textures, animation, shaders, post-processing |
+| WebXR, Meta Quest | `meta-webxr-skills` | agentic-skills | 8 skills: XR session lifecycle, rendering, input, passthrough, anchors, PWA packaging |
+
+---
+
+## Security
+
+| Signal | Skill | Confidence | Why |
+|---|---|---|---|
+| Any project | `security-guidance` | Medium | Hook-based warnings for command injection, XSS, unsafe patterns during file edits |
+
+---
+
+## Payments & Commerce
+
+| If stack contains | Skill | Source | Confidence | Why |
+|---|---|---|---|---|
+| Stripe, stripe-js, stripe-python | `stripe-integration` | personal (`~/.claude/skills/`) | High | PCI-compliant checkout, subscriptions, webhook handling, idempotency |
+
+---
+
+## Support & CRM
+
+| If stack contains | Skill | Source | Confidence | Why |
+|---|---|---|---|---|
+| Freshdesk | `freshdesk-api` | personal (`~/.claude/skills/`) | High | Ticket management, contacts, companies, support workflow automation |
+
+---
+
+## MCP & AI Integration
+
+| If stack contains | Skill | Source | Confidence | Why |
+|---|---|---|---|---|
+| MCP server code | `mcp-server-dev` | `claude-plugins-official` | High | Deployment models, tool design, auth, interactive MCP apps |
+| Anthropic SDK, Claude API | `agent-sdk-dev` | `claude-plugins-official` | High | Claude Agent SDK patterns, tool use, multi-agent orchestration |
+
+---
+
+## Workflow Plugins (use with awareness of Forge overlap)
+
+These plugins provide workflow automation. They overlap with Forge's own
+Supervisor and Architect workflows. **Do not recommend during init** — let
+the user decide after reviewing Forge's generated workflows.
+
+Surface these in `forge:health` only if the relevant Forge workflow is absent
+or the user explicitly asks.
+
+| Plugin | What it does | Overlap with Forge |
+|---|---|---|
+| `code-review` | Multi-agent PR code review with confidence scoring | Duplicates Supervisor review workflow |
+| `pr-review-toolkit` | Specialized agents for tests, error handling, type design | Duplicates Supervisor review workflow |
+| `commit-commands` | `/commit`, `/push`, `/pr` slash commands | Duplicates `meta-commit` workflow |
+| `feature-dev` | Feature development with exploration + architecture agents | Overlaps with Orchestrator pipeline |
+| `claude-code-setup` | Analyzes codebase and recommends hooks, skills, MCP servers | Complementary to `forge:init` |
+| `claude-md-management` | Audits and improves CLAUDE.md files | Complementary — runs alongside Forge |
+
+---
+
+## Confidence Levels
+
+- **High** — primary language or framework detected; install without hesitation
+- **Medium** — relevant but not central to the stack; user should decide
+- **Low** — generally useful; surface in health report, not init prompt
+
+---
+
+## Persona Integration Pattern
+
+When a skill is installed, Forge-generated personas should invoke it explicitly
+at the relevant workflow step — not mention it in a notes section.
+
+Template (fill in skill name and trigger context):
+
+```
+When [doing X], YOU MUST invoke the `<skill-name>` skill before proceeding.
+That skill provides universal [domain] technique knowledge; the stack checklist
+provides project-specific conventions. Both layers are required. No exceptions.
+```
+
+Apply this to whichever workflow step overlaps with the skill's domain:
+- Architect reviewing a plan → invoke LSP skill + domain technique skill
+- Supervisor reviewing implementation → invoke LSP skill + domain technique skill
+- Engineer implementing → invoke LSP skill at task start
+
+LSP skills in particular should be wired into every Engineer workflow that
+touches the language, not just review steps.

package/dist/forge-payload/meta/skills/meta-architect-skills.md

@@ -0,0 +1,43 @@
+---
+id: architect-skills
+name: Architect Meta-Skills
+description: Core capabilities and toolsets for the Architect role.
+role: Architect
+applies_to: [architect]
+summary: >
+  High-level system design, strategic planning, and architecture review
+  capabilities that prioritise scalability, maintainability, and integrity.
+capabilities:
+  - Evaluate system structure for debt and bottlenecks
+  - Select design patterns and define interface contracts
+  - Map technical roadmaps across sprints
+  - Perform trade-off and scalability analysis
+  - Review implementations for architectural drift
+file_ref: .forge/skills/architect-skills.md
+---
+
+## Generation Instructions
+
+When generating the project-specific skill set for the Architect role in `.forge/skills/architect-skills.md`, the generator must:
+1. Cross-reference the `installedSkills` list in `.forge/config.json`.
+2. Map the universal skills listed below to the specific implementation names found in `installedSkills`.
+3. Focus on high-level analysis, system design, and strategic planning tools.
+4. Ensure the resulting skill set prioritizes scalability, maintainability, and architectural integrity.
+
+## Skill Set
+
+### 🏗️ System Design & Modeling
+- **Architecture Analysis**: Evaluating the current system structure to identify technical debt and bottlenecks.
+- **Design Pattern Selection**: Determining the most appropriate patterns (e.g., Microservices, Event-driven) for new features.
+- **Data Modeling**: Designing efficient database schemas and data flow diagrams.
+- **Interface Specification**: Defining clear API contracts and communication protocols between components.
+
+### 🗺️ Strategic Planning
+- **Technical Roadmap**: Mapping out the evolution of the system over multiple sprints.
+- **Trade-off Analysis**: Weighing the pros and cons of different technical approaches (e.g., Build vs. Buy).
+- **Complexity Management**: Breaking down large architectural goals into manageable technical tasks.
+
+### 🔍 High-Level Review
+- **Architecture Review**: Ensuring that implementations align with the intended design and don't introduce "architectural drift".
+- **Scalability Assessment**: Analyzing how the system will handle growth in users or data volume.
+- **Security Modeling**: Identifying potential attack vectors and designing mitigation strategies.

package/dist/forge-payload/meta/skills/meta-bug-fixer-skills.md

@@ -0,0 +1,43 @@
+---
+id: bug-fixer-skills
+name: Bug-Fixer Meta-Skills
+description: Core capabilities and toolsets for the Bug-Fixer role.
+role: BugFixer
+applies_to: [bug-fixer]
+summary: >
+  Rapid reproduction, isolation, surgical remediation, and regression-safe
+  verification of reported bugs.
+capabilities:
+  - Create minimal reproducible examples
+  - Bisect commits and analyse logs to locate failure
+  - Apply surgical fixes that avoid collateral damage
+  - Write a regression test that fails without the fix and passes with it
+  - Verify fixes across environments and under stress
+file_ref: .forge/skills/bug-fixer-skills.md
+---
+
+## Generation Instructions
+
+When generating the project-specific skill set for the Bug-Fixer role in `.forge/skills/bug-fixer-skills.md`, the generator must:
+1. Cross-reference the `installedSkills` list in `.forge/config.json`.
+2. Map the universal skills listed below to the specific implementation names found in `installedSkills`.
+3. Emphasize tools for rapid reproduction, isolation, and verification.
+4. Ensure the resulting skill set focuses on minimizing regression and maximizing fix stability.
+
+## Skill Set
+
+### 🐛 Triage & Isolation
+- **Reproduction**: Creating minimal, reproducible examples of the reported bug.
+- **Log Analysis**: Sifting through system and application logs to identify the point of failure.
+- **State Inspection**: Using debuggers or telemetry to examine the system state at the moment of the crash.
+- **Bisection**: Using git bisect or similar techniques to find the commit that introduced the bug.
+
+### 🛠️ Targeted Remediation
+- **Surgical Fixes**: Applying the most precise fix possible to avoid collateral damage.
+- **Regression Prevention**: Writing a specific test case that fails without the fix and passes with it.
+- **Hotfix Deployment**: Managing the rapid release of critical fixes to production environments.
+
+### 🧪 Verification & Validation
+- **Stress Testing**: Subjecting the fix to high loads or unusual inputs to ensure stability.
+- **Cross-Environment Testing**: Verifying the fix across different OSs, browsers, or hardware configurations.
+- **Verification Sign-off**: Providing evidence that the bug is resolved and no new issues were introduced.

package/dist/forge-payload/meta/skills/meta-collator-skills.md

@@ -0,0 +1,41 @@
+---
+id: collator-skills
+name: Collator Meta-Skills
+description: Core capabilities and toolsets for the Collator role.
+role: Collator
+applies_to: [collator]
+summary: >
+  Deterministic data aggregation, markdown regeneration, and store
+  consistency — accurate writeback, entity linking, and index maintenance.
+capabilities:
+  - Regenerate MASTER_INDEX.md, TIMESHEET.md, and sprint summaries
+  - Cross-reference tasks, bugs, features, events in the store
+  - Detect referential integrity gaps and schema drift
+  - Merge multi-source subagent outputs atomically
+file_ref: .forge/skills/collator-skills.md
+---
+
+## Generation Instructions
+
+When generating the project-specific skill set for the Collator role in `.forge/skills/collator-skills.md`, the generator must:
+1. Cross-reference the `installedSkills` list in `.forge/config.json`.
+2. Map the universal skills listed below to the specific implementation names found in `installedSkills`.
+3. Emphasize tools for data aggregation, markdown regeneration, and store consistency.
+4. Ensure the resulting skill set focuses on accurate writeback, entity linking, and index maintenance.
+
+## Skill Set
+
+### 📑 Data Aggregation & Writeback
+- **Markdown Regeneration**: Rebuilding `MASTER_INDEX.md`, sprint summaries, and progress reports from the JSON store.
+- **Entity Linking**: Ensuring tasks, bugs, features, and events are correctly cross-referenced in the store.
+- **Store Writeback**: Persisting generated artifacts using `store-cli.cjs` via the Store Custodian skill.
+
+### 🔍 Consistency & Validation
+- **Referential Integrity**: Detecting orphaned entities, broken links, and stale references across store records.
+- **Index Reconciliation**: Comparing `MASTER_INDEX.md` against the actual store contents and flagging drift.
+- **Schema Compliance**: Validating that store records conform to their respective JSON schemas before writeback.
+
+### 🔄 Synchronization
+- **Multi-Source Merge**: Combining data from multiple subagent outputs into a single coherent artifact.
+- **Change Detection**: Identifying which store records have been modified since the last collation pass.
+- **Atomic Updates**: Ensuring that partial writeback failures do not leave the store in an inconsistent state.

package/dist/forge-payload/meta/skills/meta-engineer-skills.md

@@ -0,0 +1,43 @@
+---
+id: engineer-skills
+name: Engineer Meta-Skills
+description: Core capabilities and toolsets for the Engineer role.
+role: Engineer
+applies_to: [engineer]
+summary: >
+  Concrete capabilities the Engineer persona must use to execute a task:
+  code analysis, implementation, testing, debugging, and CI/CD alignment.
+capabilities:
+  - Analyse codebases using Grep, Read, Glob
+  - Implement features per approved plans and project conventions
+  - Write unit, integration, and end-to-end tests
+  - Perform root cause analysis and impact analysis
+  - Align commits and branches with the project's git flow
+file_ref: .forge/skills/engineer-skills.md
+---
+
+## Generation Instructions
+
+When generating the project-specific skill set for the Engineer role in `.forge/skills/engineer-skills.md`, the generator must:
+1. Cross-reference the `installedSkills` list in `.forge/config.json`.
+2. Map the universal skills listed below to the specific implementation names found in `installedSkills`.
+3. Interpolate any project-specific tool names or internal CLI commands used for build, test, and deployment.
+4. Ensure that the resulting skill set is actionable, providing clear triggers for when each skill should be invoked.
+
+## Skill Set
+
+### 🛠️ Implementation & Coding
+- **Code Analysis**: Ability to read, analyze, and understand existing codebases using `Grep`, `Read`, and `Glob`.
+- **Feature Implementation**: Converting technical designs into working code while adhering to project style guides.
+- **Refactoring**: Improving code structure without altering behavior, focusing on maintainability and efficiency.
+- **Test Writing**: Implementing unit, integration, and end-to-end tests to ensure correctness.
+
+### 🔍 Investigation & Debugging
+- **Root Cause Analysis**: Using logs, debugger tools, and hypothesis testing to isolate bugs.
+- **Impact Analysis**: Assessing how a change in one part of the system affects other components.
+- **Performance Profiling**: Identifying bottlenecks and optimizing critical paths.
+
+### ⚙️ Workflow Integration
+- **Git Mastery**: Managing branches, commits, and PRs following the project's git flow.
+- **CI/CD Alignment**: Ensuring code passes pipeline checks and is deployable.
+- **Tool Synthesis**: Creating small scripts or tools to automate repetitive engineering tasks.

package/dist/forge-payload/meta/skills/meta-generic-skills.md

@@ -0,0 +1,58 @@
+---
+id: generic-skills
+name: Generic Meta-Skills
+description: Baseline capabilities for support and orchestration roles.
+role: Generic
+applies_to: [orchestrator, collator, supervisor]
+summary: >
+  Baseline coordination, information synthesis, and basic tooling that
+  every support role needs regardless of domain.
+capabilities:
+  - Schedule tasks and manage dependency resolution
+  - Hand off context between roles cleanly
+  - Aggregate progress from multiple agents
+  - Perform basic file and git operations
+  - Monitor logs and events for triggers
+file_ref: .forge/skills/generic-skills.md
+---
+
+## Generation Instructions
+
+When generating the project-specific skill set for support roles (e.g., Orchestrator, Collator) in `.forge/skills/generic-skills.md`, the generator must:
+1. Cross-reference the `installedSkills` list in `.forge/config.json`.
+2. Map the universal skills listed below to the specific implementation names found in `installedSkills`.
+3. Focus on data aggregation, communication, and process management.
+4. Ensure the resulting skill set is lightweight and focused on efficiency.
+
+## Skill Set
+
+### 🔄 Coordination & Orchestration
+- **Task Scheduling**: Managing the sequence of task execution and dependency resolution.
+- **Agent Handoff**: Ensuring smooth transitions of context and responsibility between different roles.
+- **Status Reporting**: Aggregating progress from multiple agents into a concise summary.
+
+### 📑 Information Synthesis
+- **Data Collation**: Gathering disparate pieces of information into a structured format.
+- **Summary Generation**: Distilling complex technical discussions into key takeaways and action items.
+- **Artifact Mapping**: Ensuring that tasks, bugs, and features are correctly linked in the store.
+
+### 🛠️ Basic Tooling
+- **File Management**: Basic use of `Read`, `Write`, and `Glob` for housekeeping.
+- **Git Basics**: Performing simple commits and status checks.
+- **Log Monitoring**: Watching for specific event patterns to trigger transitions.
+
+## Orchestrator Iron Laws
+
+These laws apply to every orchestrator workflow (task pipeline and bug-fix pipeline). They are the non-negotiable invariants of the phase loop.
+
+**YOU MUST NOT advance a phase until its gate checks pass.** Skipping a gate because "it's probably fine" or "it's a small change" is not allowed. No exceptions.
+
+**Review ordering is hardcoded:** spec compliance review ALWAYS runs before code quality review. Never reverse this. Checking quality before confirming correctness is wasted work.
+
+**Revision loop exhaustion is an escalation trigger.** If max_iterations is reached without approval, escalate to the human immediately. Do NOT approve to unblock the pipeline.
+
+**Always read the verdict from the artifact.** Never assume approval because the review phase ran without error. The artifact is the source of truth.
+
+**Phase banners are orchestrator-owned.** Do NOT include banner-first instructions in subagent prompts. The orchestrator displays the badge before spawning and the exit signal after return.
+
+**No emoji in machine-readable fields.** Emoji belong only in stdout announcements and human-facing Markdown. JSON fields use plain values only.

package/dist/forge-payload/meta/skills/meta-qa-engineer-skills.md

@@ -0,0 +1,46 @@
+---
+id: qa-engineer-skills
+name: QA Engineer Meta-Skills
+description: Core capabilities and toolsets for the QA Engineer role.
+role: QAEngineer
+applies_to: [qa-engineer]
+summary: >
+  Test strategy, coverage analysis, and verification that prevents
+  regressions and validates acceptance criteria against implementations.
+capabilities:
+  - Design test plans mapping each acceptance criterion to test cases
+  - Analyse coverage reports and identify untested paths
+  - Probe edge cases, boundary conditions, and unusual inputs
+  - Detect flaky tests and enforce quality gates
+file_ref: .forge/skills/qa-engineer-skills.md
+---
+
+## Generation Instructions
+
+When generating the project-specific skill set for the QA Engineer role in `.forge/skills/qa-engineer-skills.md`, the generator must:
+1. Cross-reference the `installedSkills` list in `.forge/config.json`.
+2. Map the universal skills listed below to the specific implementation names found in `installedSkills`.
+3. Emphasize tools for test strategy, coverage analysis, and verification.
+4. Ensure the resulting skill set focuses on preventing regressions and validating acceptance criteria.
+
+## Skill Set
+
+### 🧪 Test Strategy & Design
+- **Test Plan Creation**: Designing comprehensive test plans that cover functional, integration, and edge-case scenarios.
+- **Acceptance Criteria Validation**: Mapping each acceptance criterion to specific test cases that prove compliance.
+- **Risk-Based Testing**: Prioritizing test effort on areas with the highest defect probability or business impact.
+
+### 📊 Coverage & Analysis
+- **Coverage Analysis**: Interpreting code coverage reports and identifying untested paths.
+- **Gap Identification**: Finding scenarios not covered by the existing test suite and proposing new tests.
+- **Regression Risk Assessment**: Evaluating the blast radius of code changes to determine regression risk.
+
+### ✅ Verification & Validation
+- **Build Verification**: Running the project's build and test commands to confirm that implementation meets specifications.
+- **Specification Compliance**: Checking that the implementation matches the approved plan's acceptance criteria.
+- **Edge Case Discovery**: Probing boundary conditions, error paths, and unusual input combinations.
+
+### 🔄 Continuous Quality
+- **Test Maintenance**: Keeping the test suite current as the codebase evolves.
+- **Flakiness Detection**: Identifying and resolving non-deterministic test failures.
+- **Quality Gates**: Enforcing test pass requirements before marking tasks as complete.

package/dist/forge-payload/meta/skills/meta-supervisor-skills.md

@@ -0,0 +1,43 @@
+---
+id: supervisor-skills
+name: Supervisor Meta-Skills
+description: Core capabilities and toolsets for the Supervisor and QA role.
+role: Supervisor
+applies_to: [supervisor]
+summary: >
+  Quality assurance, review governance, and defect feedback — verifying
+  specifications, test coverage, and compliance before work advances.
+capabilities:
+  - Validate requirements against implementations
+  - Review test plans for coverage and effectiveness
+  - Conduct code reviews for logic, style, and maintainability
+  - Maintain audit trails and compliance checks
+  - Orchestrate approval transitions from implementing to review-approved
+file_ref: .forge/skills/supervisor-skills.md
+---
+
+## Generation Instructions
+
+When generating the project-specific skill set for the Supervisor role in `.forge/skills/supervisor-skills.md`, the generator must:
+1. Cross-reference the `installedSkills` list in `.forge/config.json`.
+2. Map the universal skills listed below to the specific implementation names found in `installedSkills`.
+3. Include triggers for quality gates, review cycles, and validation checks.
+4. Ensure the resulting skill set emphasizes verification, correctness, and adherence to specifications.
+
+## Skill Set
+
+### ✅ Quality Assurance & Verification
+- **Requirement Validation**: Comparing implemented features against the original specifications and acceptance criteria.
+- **Test Plan Review**: Evaluating the coverage and effectiveness of the Engineer's test suite.
+- **Edge Case Discovery**: Identifying potential failure modes and boundary conditions that may have been missed.
+- **Regression Testing**: Ensuring that new changes do not break existing functionality.
+
+### 📋 Review & Governance
+- **Code Review**: Conducting thorough reviews of PRs for logic, style, and maintainability.
+- **Audit Trails**: Ensuring that all changes are documented and linked to the appropriate tasks/bugs.
+- **Compliance Checking**: Verifying that the code adheres to organizational standards and security policies.
+
+### 📈 Feedback & Coordination
+- **Defect Reporting**: Clearly documenting bugs and assigning them back to engineers with reproducible steps.
+- **Progress Tracking**: Monitoring task completion and identifying blockers in the pipeline.
+- **Approval Orchestration**: Managing the transition of tasks from `implementing` to `review-approved`.

package/dist/forge-payload/meta/store-schema/bug.schema.md

@@ -0,0 +1,71 @@
+# Store Schema: Bug
+
+## File Location
+
+`.forge/store/bugs/{BUG_ID}.json`
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `bugId` | string | yes | e.g. `ACME-BUG-01` |
+| `title` | string | yes | Bug title |
+| `description` | string | no | Detailed description |
+| `severity` | enum | yes | `critical` / `major` / `minor` |
+| `status` | enum | yes | See status values below |
+| `path` | string | yes | Relative path to bug artifact directory |
+| `rootCauseCategory` | enum | no | See categories below |
+| `similarBugs` | string[] | no | Bug IDs with similar root cause |
+| `checklistItemAdded` | boolean | no | Whether a stack-checklist item was added |
+| `businessRuleUpdated` | boolean | no | Whether business domain docs were updated |
+| `reportedAt` | string | yes | ISO 8601 timestamp |
+| `resolvedAt` | string | no | ISO 8601 timestamp |
+
+## Status Values
+
+`reported` → `triaged` → `in-progress` → `fixed`
+
+`fixed` is the terminal state — set by the commit phase after the bug-fix
+commit lands. The architect's approval signal travels through
+`bug.summaries.approve.verdict` (read by `read-verdict.cjs §
+BUG_PHASE_VERDICT_SOURCE`), not through `bug.status`. Earlier revisions of
+this schema included `approved` and `verified` enum values; they were
+removed because no workflow phase wrote them and their mere presence in the
+schema invited LLM-translated task workflows to attempt `update-status bug
+... approved`, which produced FORGE-BUG-002.
+
+## Root Cause Categories
+
+`validation` / `auth` / `business-rule` / `data-integrity` / `race-condition` / `integration` / `configuration` / `regression`
+
+## JSON Schema
+
+This block is the canonical machine-readable definition embedded in `validate-store.cjs`.
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forge/bug.schema.json",
+  "title": "Bug",
+  "type": "object",
+  "required": ["bugId", "title", "severity", "status", "path", "reportedAt"],
+  "properties": {
+    "bugId":                { "type": "string" },
+    "title":                { "type": "string" },
+    "description":          { "type": "string" },
+    "severity":             { "type": "string", "enum": ["critical", "major", "minor"] },
+    "status":               { "type": "string", "enum": ["reported", "triaged", "in-progress", "fixed"] },
+    "path":                 { "type": "string" },
+    "rootCauseCategory": {
+      "type": "string",
+      "enum": ["validation", "auth", "business-rule", "data-integrity", "race-condition", "integration", "configuration", "regression"]
+    },
+    "similarBugs":          { "type": "array", "items": { "type": "string" } },
+    "checklistItemAdded":   { "type": "boolean" },
+    "businessRuleUpdated":  { "type": "boolean" },
+    "reportedAt":           { "type": "string", "format": "date-time" },
+    "resolvedAt":           { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}
+```

package/dist/forge-payload/meta/store-schema/event.schema.md

@@ -0,0 +1,76 @@
+# Store Schema: Event
+
+## File Location
+
+`.forge/store/events/{SPRINT_ID}/{EVENT_ID}.json`
+
+## Event ID Format
+
+`{ISO_TIMESTAMP}_{TASK_ID}_{ROLE}_{ACTION}`
+
+Example: `20260415T141523000Z_ACME-S02-T03_engineer_implement`
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `eventId` | string | yes | Unique event identifier |
+| `taskId` | string | yes | Task this event belongs to |
+| `sprintId` | string | yes | Sprint this event belongs to |
+| `role` | string | yes | Agent role (Engineer, Supervisor, Architect) |
+| `action` | string | yes | Command invoked (e.g. `/implement`) |
+| `phase` | string | yes | Pipeline phase (plan, review-plan, implement, etc.) |
+| `iteration` | integer | yes | Which iteration of this phase (1-based) |
+| `startTimestamp` | string | yes | ISO 8601 |
+| `endTimestamp` | string | yes | ISO 8601 |
+| `durationMinutes` | number | yes | Computed duration |
+| `model` | string | yes | Full model identifier as reported by the host CLI (e.g. `claude-sonnet-4-6`, `gpt-4o`, `o3`) — use the full ID, not a short alias |
+| `provider` | string | yes | Provider name (e.g. `anthropic`, `zai`, `openai`, `bedrock`) — required for cost attribution since same model is priced differently across providers |
+| `verdict` | string | no | For review phases: Approved / Revision Required |
+| `notes` | string | no | Free-form notes |
+| `inputTokens` | integer | no | Input token count (minimum 0). Omit when telemetry is unavailable — never write zero as a placeholder. |
+| `outputTokens` | integer | no | Output token count (minimum 0) |
+| `cacheReadTokens` | integer | no | Cache-read token count (minimum 0) |
+| `cacheWriteTokens` | integer | no | Cache-write token count (minimum 0) |
+| `tokenSource` | enum | no | `reported` / `estimated` — how token counts were obtained. Omit when no telemetry is available; events without tokens surface as husks in collate reports. |
+
+> **Cost note:** `estimatedCostUSD` is NOT persisted on event records. Cost is derived at collate time from `(provider, model, tokens)` via `tools/lib/pricing.cjs`. This keeps the dataset truthful when pricing changes.
+
+## JSON Schema
+
+This block is the canonical machine-readable definition embedded in `validate-store.cjs`.
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forge/event.schema.json",
+  "title": "Event",
+  "type": "object",
+  "required": [
+    "eventId", "taskId", "sprintId", "role", "action",
+    "phase", "iteration", "startTimestamp", "endTimestamp", "durationMinutes", "model", "provider"
+  ],
+  "properties": {
+    "eventId":         { "type": "string" },
+    "taskId":          { "type": "string" },
+    "sprintId":        { "type": "string" },
+    "role":            { "type": "string" },
+    "action":          { "type": "string" },
+    "phase":           { "type": "string" },
+    "iteration":       { "type": "integer", "minimum": 1 },
+    "startTimestamp":  { "type": "string", "format": "date-time" },
+    "endTimestamp":    { "type": "string", "format": "date-time" },
+    "durationMinutes": { "type": "number", "minimum": 0 },
+    "model":           { "type": "string" },
+    "provider":        { "type": "string", "maxLength": 60 },
+    "verdict":            { "type": "string" },
+    "notes":              { "type": "string" },
+    "inputTokens":        { "type": "integer", "minimum": 0 },
+    "outputTokens":       { "type": "integer", "minimum": 0 },
+    "cacheReadTokens":    { "type": "integer", "minimum": 0 },
+    "cacheWriteTokens":   { "type": "integer", "minimum": 0 },
+    "tokenSource":        { "type": "string",  "enum": ["reported", "estimated"] }
+  },
+  "additionalProperties": false
+}
+```