@entelligentsia/forgecli 0.10.0 → 0.11.2

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

@@ -0,0 +1,65 @@
+# Store Schema: Feature
+
+## File Location
+
+`.forge/store/features/{FEATURE_ID}.json`
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Format: `FEAT-NNN` |
+| `title` | string | yes | Feature title |
+| `description` | string | no | Feature description |
+| `status` | enum | yes | See status values below |
+| `requirements` | string[] | no | Plain-text requirement lines |
+| `sprints` | string[] | no | Array of sprint IDs (back-refs) |
+| `tasks` | string[] | no | Array of task IDs (back-refs) |
+| `created_at` | string | yes | ISO date-time string |
+| `updated_at` | string | no | ISO date-time string |
+
+## Relationship Notes
+
+- The fields `description`, `requirements`, `sprints`, `tasks`, and `updated_at` are **optional**.
+- The `id`, `title`, `status`, and `created_at` fields are **required**.
+- `feature_id` on sprint and task manifests is nullable for backwards compatibility.
+
+## Status Values
+
+```mermaid
+stateDiagram-v2
+    [*] --> draft
+    draft --> active
+    active --> shipped
+    active --> retired
+    shipped --> retired
+```
+
+## 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/feature.schema.json",
+  "title": "Feature",
+  "type": "object",
+  "required": ["id", "title", "status", "created_at"],
+  "properties": {
+    "id":           { "type": "string" },
+    "title":        { "type": "string" },
+    "description":  { "type": "string" },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "active", "shipped", "retired"]
+    },
+    "requirements": { "type": "array", "items": { "type": "string" } },
+    "sprints":      { "type": "array", "items": { "type": "string" } },
+    "tasks":        { "type": "array", "items": { "type": "string" } },
+    "created_at":   { "type": "string", "format": "date-time" },
+    "updated_at":   { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}
+```

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

@@ -0,0 +1,64 @@
+# Store Schema: Sprint
+
+## File Location
+
+`.forge/store/sprints/{SPRINT_ID}.json`
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `sprintId` | string | yes | e.g. `S01` |
+| `title` | string | yes | Sprint title |
+| `description` | string | no | Sprint goals (prose) |
+| `goal` | string | no | Sprint goal (single-sentence summary) |
+| `status` | enum | yes | See status values below |
+| `taskIds` | string[] | yes | Ordered list of task IDs in this sprint |
+| `features` | string[] | no | Feature IDs this sprint contributes to |
+| `feature_id` | string\|null | no | Primary feature linkage (nullable FK) |
+| `dependencies` | object | no | Task dependency edges for wave computation |
+| `executionMode` | enum | no | `sequential` / `wave-parallel` / `full-parallel` |
+| `createdAt` | string | yes | ISO 8601 timestamp |
+| `completedAt` | string | no | ISO 8601 timestamp |
+| `path` | string | no | Relative path to sprint artifact directory |
+| `humanEstimates` | object | no | `{ total: "Xh", breakdown: { taskId: "Yh" } }` |
+
+## Status Values
+
+`planning` → `active` → `completed` → `retrospective-done`
+
+Failed states: `blocked`, `partially-completed`, `abandoned`
+
+## 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/sprint.schema.json",
+  "title": "Sprint",
+  "type": "object",
+  "required": ["sprintId", "title", "status", "taskIds", "createdAt"],
+  "properties": {
+    "sprintId":       { "type": "string" },
+    "title":          { "type": "string" },
+    "description":    { "type": "string" },
+    "status": {
+      "type": "string",
+      "enum": ["planning", "active", "completed", "retrospective-done", "blocked", "partially-completed", "abandoned"]
+    },
+    "goal":           { "type": "string" },
+    "taskIds":        { "type": "array", "items": { "type": "string" } },
+    "features":       { "type": "array", "items": { "type": "string" } },
+    "feature_id":     { "type": ["string", "null"] },
+    "dependencies":   { "type": "object" },
+    "executionMode":  { "type": "string", "enum": ["sequential", "wave-parallel", "full-parallel"] },
+    "createdAt":      { "type": "string", "format": "date-time" },
+    "completedAt":    { "type": "string", "format": "date-time" },
+    "path":           { "type": "string" },
+    "humanEstimates": { "type": "object" }
+  },
+  "additionalProperties": false
+}
+```

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

@@ -0,0 +1,78 @@
+# Store Schema: Task
+
+## File Location
+
+`.forge/store/tasks/{TASK_ID}.json`
+
+## Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `taskId` | string | yes | e.g. `ACME-S01-T01` |
+| `feature_id` | string\|null | no | Primary feature linkage (nullable FK) |
+| `sprintId` | string | yes | e.g. `S01` |
+| `title` | string | yes | Task title |
+| `description` | string | no | Detailed description |
+| `status` | enum | yes | See status values below |
+| `path` | string | yes | Relative path to task artifact directory |
+| `estimate` | enum | no | `S` / `M` / `L` / `XL` |
+| `dependencies` | string[] | no | Task IDs this task depends on |
+| `knowledgeUpdates` | object[] | no | Files updated during writeback |
+| `planIterations` | integer | no | Number of plan review loops |
+| `codeReviewIterations` | integer | no | Number of code review loops |
+| `assignedModel` | string | no | Model used for implementation |
+| `pipeline` | string | no | Named pipeline to use instead of `default`. Must match a key in `config.pipelines`. When absent, the orchestrator uses the `default` pipeline. |
+
+## Status Values
+
+`draft` → `planned` → `plan-approved` → `implementing` → `implemented` → `review-approved` → `approved` → `committed`
+
+Failed states: `plan-revision-required`, `code-revision-required`, `blocked`, `escalated`, `abandoned`
+
+## Knowledge Updates Schema
+
+```json
+{
+  "file": "architecture/stack.md",
+  "section": "Celery Patterns",
+  "type": "addition | correction | removal"
+}
+```
+
+## 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/task.schema.json",
+  "title": "Task",
+  "type": "object",
+  "required": ["taskId", "sprintId", "title", "status", "path"],
+  "properties": {
+    "taskId":               { "type": "string" },
+    "feature_id":           { "type": ["string", "null"] },
+    "sprintId":             { "type": "string" },
+    "title":                { "type": "string" },
+    "description":          { "type": "string" },
+    "status": {
+      "type": "string",
+      "enum": [
+        "draft", "planned", "plan-approved", "implementing",
+        "implemented", "review-approved", "approved", "committed",
+        "plan-revision-required", "code-revision-required", "blocked", "escalated", "abandoned"
+      ]
+    },
+    "path":                 { "type": "string" },
+    "estimate":             { "type": "string", "enum": ["S", "M", "L", "XL"] },
+    "dependencies":         { "type": "array", "items": { "type": "string" } },
+    "knowledgeUpdates":     { "type": "array" },
+    "planIterations":       { "type": "integer", "minimum": 0 },
+    "codeReviewIterations": { "type": "integer", "minimum": 0 },
+    "assignedModel":        { "type": "string" },
+    "pipeline":             { "type": "string" }
+  },
+  "additionalProperties": false
+}
+```

package/dist/forge-payload/meta/templates/meta-code-review.md

@@ -0,0 +1,26 @@
+# Meta-Template: Code Review
+
+## Purpose
+
+Defines the structure of CODE_REVIEW.md — the Supervisor's verdict on
+the implementation.
+
+## Sections
+
+### Required
+- **Verdict** — `Approved` / `Approved with supervisor corrections` / `Revision Required`
+- **Review Summary** — overall assessment
+- **Checklist Results** — stack-checklist.md items checked, with pass/fail
+- **Issues Found** — numbered list with severity, file:line, description, fix suggestion
+
+### If Revision Required
+- **Required Changes** — numbered, actionable items
+- **Priority** — which items block approval
+
+### If Approved
+- **Advisory Notes** — non-blocking observations for future consideration
+
+## Generation Instructions
+- Load the project's stack-checklist.md as the review criteria source
+- Include framework-specific review categories
+- Reference the project's auth pattern in the security section

package/dist/forge-payload/meta/templates/meta-plan-review.md

@@ -0,0 +1,28 @@
+# Meta-Template: Plan Review
+
+## Purpose
+
+Defines the structure of PLAN_REVIEW.md — the Supervisor's verdict on
+the implementation plan.
+
+## Sections
+
+### Required
+- **Verdict** — `Approved` / `Revision Required`
+- **Review Summary** — overall assessment of the plan
+- **Feasibility** — is the approach realistic and scoped correctly?
+- **Security** — are auth and validation addressed?
+- **Architecture Alignment** — does it follow established patterns?
+- **Testing Strategy** — is the planned coverage adequate?
+
+### If Revision Required
+- **Required Changes** — numbered, actionable items
+- **Priority** — which items block approval
+
+### If Approved
+- **Advisory Notes** — suggestions for implementation (non-blocking)
+
+## Generation Instructions
+- Reference the project's architecture sub-docs for alignment checks
+- Include stack-specific security considerations
+- Reference the project's test expectations

package/dist/forge-payload/meta/templates/meta-plan.md

@@ -0,0 +1,28 @@
+# Meta-Template: Implementation Plan
+
+## Purpose
+
+Defines the structure of PLAN.md — the Engineer's technical approach
+document, reviewed by the Supervisor before implementation begins.
+
+## Sections
+
+### Required
+- **Objective** — what this plan achieves
+- **Approach** — high-level strategy
+- **Files to Modify** — list of files with rationale
+- **Testing Strategy** — what tests to write/modify
+- **Acceptance Criteria** — copied from task prompt, mapped to implementation steps
+- **Operational Impact** — deployment, migrations, monitoring
+
+### Stack-Specific (added based on detection)
+- **Data Model** subsections per framework (Django Models, Prisma Schema, etc.)
+- **API Layer** subsections (DRF Serializers/Views, Express Routes, etc.)
+- **Frontend** subsections (React Components, Vue Components, etc.)
+- **Task Queue** subsections (Celery Tasks, Sidekiq Jobs, etc.)
+- **Database Migrations** with framework-specific verification command
+
+## Generation Instructions
+- Add framework-specific subsections based on detected stack
+- Test evidence section should expect output format of project's test runner
+- Include the project's migration check command if applicable

package/dist/forge-payload/meta/templates/meta-progress.md

@@ -0,0 +1,25 @@
+# Meta-Template: Progress Report
+
+## Purpose
+
+Defines the structure of PROGRESS.md — the Engineer's completion report
+after implementation, reviewed by the Supervisor.
+
+## Sections
+
+### Required
+- **Summary** — what was done
+- **Testing Results** — copy of test output (must include actual output)
+- **Files Changed** — manifest with brief description per file
+- **Acceptance Criteria Status** — each criterion marked pass/fail
+
+### Optional
+- **Build Output** — if frontend/build step was involved
+- **Migration Status** — if database changes were made
+- **Knowledge Updates** — what was written back to the knowledge base
+- **Notes** — anything the reviewer should know
+
+## Generation Instructions
+- Test evidence section should expect the project's specific test runner output
+- Include build verification if the project has a build step
+- Include migration verification if the project has a migration system

package/dist/forge-payload/meta/templates/meta-retrospective.md

@@ -0,0 +1,28 @@
+# Meta-Template: Sprint Retrospective
+
+## Purpose
+
+Defines the structure of the sprint retrospective document — metrics,
+learnings, and improvements.
+
+## Sections
+
+### Required
+- **Sprint Summary** — tasks completed, failed, carried over
+- **Metrics** — plan iterations, code review iterations, time per task
+- **What Went Well** — patterns that worked
+- **What to Improve** — friction points, recurring issues
+- **Knowledge Base Updates** — what was confirmed, added, or removed
+- **Stack Checklist Changes** — items added or pruned
+
+### Optional
+- **Workflow Improvements** — proposed edits to workflow files
+- **Bug Pattern Analysis** — recurring root cause categories
+- **Merge Conflicts** — if parallel mode, what conflicted and why
+- **Recommendations for Next Sprint** — scope, focus, mode
+
+## Generation Instructions
+- Reference the project's sprint artifact paths for data gathering
+- Reference the project's domain docs and stack checklist
+- Include the project's workflow file paths for proposed edits
+- Reference the project's specific tech debt areas

package/dist/forge-payload/meta/templates/meta-sprint-manifest.md

@@ -0,0 +1,26 @@
+# Meta-Template: Sprint Manifest
+
+## Purpose
+
+Defines the structure of the sprint planning output — the task breakdown,
+estimates, and dependency graph for a sprint.
+
+## Sections
+
+### Required
+- **Sprint ID** — using project prefix format
+- **Sprint Title** — descriptive name
+- **Goals** — what this sprint achieves
+- **Task Table** — ID, title, estimate, dependencies, status
+- **Dependency Graph** — Mermaid diagram showing task relationships
+- **Execution Mode** — sequential / wave-parallel / full-parallel
+
+### Optional
+- **Risks** — known risks for this sprint
+- **Carry-Over** — items from previous sprint
+- **Technical Debt** — planned debt repayment
+
+## Generation Instructions
+- Use the project's ID format (PREFIX-S{NN}-T{NN})
+- Reference the project's entity model for task scoping
+- Include the project's operational impact categories

package/dist/forge-payload/meta/templates/meta-sprint-requirements.md

@@ -0,0 +1,91 @@
+# Meta-Template: Sprint Requirements
+
+## Purpose
+
+Defines the structure of `SPRINT_REQUIREMENTS.md` — the output of the sprint
+intake interview. This document is the primary input to sprint planning.
+Every field marked Required must be completed before planning begins.
+
+## Sections
+
+### Required
+
+- **Sprint ID** — next sequential ID using project prefix (e.g. ACME-S03)
+- **Sprint Goals** — 1–3 concrete outcomes; each stated as an observable result
+- **In Scope** — itemised list of must-have features, fixes, or changes for this sprint
+- **Out of Scope** — explicit list of things not being done this sprint
+- **Acceptance Criteria** — per in-scope item: specific, testable conditions for approval
+
+### Conditional (include when raised during intake)
+
+- **Nice-to-Have** — items to attempt only if must-haves are complete
+- **Constraints** — technical, data, dependency, or timeline constraints
+- **Risks** — identified unknowns or blockers with a brief mitigation note
+- **Carry-Over** — items from the previous sprint with a note on their status
+
+### Metadata
+
+- **Captured** — date and sprint number
+- **Source** — "sprint-intake interview" (confirms document came from intake, not assumptions)
+
+## Document Shape
+
+```markdown
+# Sprint Requirements — {SPRINT_ID}
+
+**Captured:** {DATE}
+**Source:** sprint-intake interview
+
+## Goals
+
+1. {GOAL_1}
+2. {GOAL_2}
+
+## In Scope
+
+### {ITEM_TITLE} [must-have]
+{One-line description}
+
+**Acceptance criteria:**
+- {CRITERION_1}
+- {CRITERION_2}
+
+### {ITEM_TITLE} [must-have]
+...
+
+## Out of Scope
+
+- {EXPLICIT_EXCLUSION_1}
+- {EXPLICIT_EXCLUSION_2}
+
+## Nice-to-Have (attempt if time allows)
+
+- {ITEM}
+
+## Constraints
+
+- **Technical:** {CONSTRAINT}
+- **Data:** {CONSTRAINT}
+- **Dependencies:** {CONSTRAINT}
+- **Timeline:** {CONSTRAINT}
+
+## Risks
+
+| Risk | Likelihood | Mitigation |
+|---|---|---|
+| {RISK} | High / Medium / Low | {MITIGATION} |
+
+## Carry-Over from {PREV_SPRINT_ID}
+
+| Item | Status | Notes |
+|---|---|---|
+| {ITEM} | Partial / Blocked | {NOTE} |
+```
+
+## Generation Instructions
+
+- Replace `{SPRINT_ID}` with the project's next sequential sprint ID
+- Acceptance criteria must be concrete and testable — reject vague criteria
+  (e.g. "works well") during generation
+- Include only sections relevant to this sprint — omit empty conditional sections
+- The Carry-Over section requires reading the previous sprint's store entry

package/dist/forge-payload/meta/templates/meta-task-prompt.md

@@ -0,0 +1,26 @@
+# Meta-Template: Task Prompt
+
+## Purpose
+
+Defines the structure of a task prompt — the input document that starts
+every task through the pipeline.
+
+## Sections
+
+### Required
+- **Title** — one-line summary
+- **Objective** — what the task achieves (user-facing value)
+- **Acceptance Criteria** — numbered, testable conditions for completion
+- **Context** — relevant background, links to related tasks/bugs
+
+### Optional (added based on stack detection)
+- **Entities** — which business entities are involved
+- **API Changes** — new/modified endpoints (if API project)
+- **UI Changes** — new/modified components (if frontend project)
+- **Data Model Changes** — schema/migration needs
+- **Operational Impact** — deployment, monitoring, rollback considerations
+
+## Generation Instructions
+- Add entity references from the project's business domain
+- Add stack-specific acceptance criteria patterns
+- Include the project's ID format in the template header

package/dist/forge-payload/meta/tool-specs/collate.spec.md

@@ -0,0 +1,88 @@
+# Tool Spec: collate
+
+## Purpose
+
+Regenerate markdown views from the JSON store. Deterministic — no AI needed.
+
+## Inputs
+
+- `.forge/config.json` — project prefix, paths, description
+- `.forge/store/sprints/*.json`
+- `.forge/store/tasks/*.json`
+- `.forge/store/bugs/*.json`
+- `.forge/store/features/*.json`
+- `.forge/store/events/{SPRINT_ID}/*.json`
+- Existing `engineering/MASTER_INDEX.md` (to preserve static sections)
+
+## Outputs
+
+1. `engineering/MASTER_INDEX.md`
+2. `engineering/sprints/{SPRINT_ID}/TIMESHEET.md` (per sprint)
+3. `engineering/bugs/TIMESHEET.md`
+4. `engineering/features/INDEX.md` (feature registry)
+5. `engineering/features/{FEATURE_ID}/INDEX.md` (per-feature page)
+6. `INDEX.md` (per sprint, task, bug directory)
+7. `.forge/store/COLLATION_STATE.json`
+
+## CLI Interface
+
+```
+<tool> collate              # all sprints
+<tool> collate S01          # single sprint + master index
+<tool> collate --dry-run    # preview only
+```
+
+Exit 0 on success, 1 on validation error.
+
+## Error Handling
+
+- Wrap the entire entry point in a top-level exception handler.
+- On unexpected errors (missing store files, bad JSON, unhandled exceptions),
+  print a clear one-line message to stderr and exit 1.
+- Never let the tool crash with an unhandled exception or stack trace visible
+  to the caller — all errors are caught and reported cleanly.
+- Python pattern:
+  ```python
+  if __name__ == "__main__":
+      try:
+          sys.exit(main())
+      except Exception as e:
+          print(f"Error: {e}", file=sys.stderr)
+          sys.exit(1)
+  ```
+- JS/TS pattern:
+  ```js
+  process.on('uncaughtException', (e) => {
+      process.stderr.write(`Error: ${e.message}\n`);
+      process.exit(1);
+  });
+  ```
+
+## Algorithm
+
+1. Read `.forge/config.json` for prefix, paths, project description
+2. Validate store: tasks/ has JSON files, required fields present
+3. Load all sprint JSON, sort by sprint number ascending
+4. Load all task JSON, group by sprintId
+5. Load all bug JSON, sort by bug number
+6. Load all feature JSON from `.forge/store/features/`
+7. Read existing `engineering/MASTER_INDEX.md`, extract preserved sections by `##` heading
+8. Build Feature Registry section: link to `features/INDEX.md` (or placeholder if none)
+9. Build Sprint Registry: table with progress (completed/total)
+10. Build Task Registry: grouped by sprint (most recent first)
+11. Build Bug Registry: open first (asc), then resolved (desc)
+12. Write `engineering/MASTER_INDEX.md`: config header → preserved → generated
+    - Generated sections order: Feature Registry → Sprint Registry → Task Registry → Bug Registry
+13. Write `engineering/features/INDEX.md`: table of all features (ID, title, status, sprint count, task count)
+14. For each feature: write `engineering/features/{FEATURE_ID}/INDEX.md` with detail page
+15. For each sprint: events → estimates table + activity log → TIMESHEET.md
+16. For each directory: discover artifacts → INDEX.md navigation hub
+17. Write `.forge/store/COLLATION_STATE.json`
+
+## Formatting Rules
+
+- Markdown pipe tables
+- Timestamps truncated to minutes
+- Duration: <60m → "Nm", >=60m → "Nh Mm"
+- IDs hyperlink to INDEX.md via relative paths
+- Generated files start with `<!-- GENERATED -->` comment