chore: add mission infrastructure for execution loop validation system
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
gsxdsm
20
.factory/init.sh
Executable file
20
.factory/init.sh
Executable file
@@ -0,0 +1,20 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Mission init script — idempotent environment setup
|
||||
# Runs at the start of each worker session
|
||||
|
||||
MISSION_ROOT="$(git -C "$(dirname "$0")" rev-parse --show-toplevel 2>/dev/null || echo "$(dirname "$0")/../..")"
|
||||
|
||||
echo "[init] Mission: Enhance Mission Execution Loop"
|
||||
echo "[init] Root: $MISSION_ROOT"
|
||||
|
||||
# Ensure dependencies are installed
|
||||
if [ ! -d "$MISSION_ROOT/node_modules" ]; then
|
||||
echo "[init] Installing dependencies..."
|
||||
cd "$MISSION_ROOT" && pnpm install --frozen-lockfile
|
||||
else
|
||||
echo "[init] Dependencies already installed."
|
||||
fi
|
||||
|
||||
echo "[init] Environment ready."
|
||||
122
.factory/library/architecture.md
Normal file
122
.factory/library/architecture.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# Architecture
|
||||
|
||||
How the mission execution loop validation system works.
|
||||
|
||||
## What belongs here
|
||||
|
||||
High-level system architecture: components, relationships, data flows, invariants.
|
||||
NOT implementation details — those go in AGENTS.md or code comments.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The mission validation system extends Fusion's existing mission hierarchy with a Factory-style implementation → validation → fix cycle. After a task completes, an AI agent validates the implementation against contract assertions. If validation fails, a fix feature is generated and the cycle repeats.
|
||||
|
||||
## Data Hierarchy (Existing + New)
|
||||
|
||||
```
|
||||
Mission
|
||||
└── Milestone
|
||||
├── ContractAssertion[] (what "done" means — many per milestone)
|
||||
└── Slice
|
||||
└── MissionFeature
|
||||
├── loopState (idle → implementing → validating → passed/needs_fix/blocked)
|
||||
├── implementationAttemptCount
|
||||
├── validatorAttemptCount
|
||||
├── ValidatorRun[] (each validation attempt)
|
||||
│ └── ValidatorFailure[] (what went wrong)
|
||||
├── FixFeatureLineage (if generated as fix)
|
||||
└── Task (linked for execution)
|
||||
|
||||
ContractAssertion ←→ MissionFeature (many-to-many via link table)
|
||||
```
|
||||
|
||||
## Component Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ CLI Layer │
|
||||
│ dashboard.ts / serve.ts │
|
||||
│ (instantiates MissionExecutionLoop) │
|
||||
└───────────────┬─────────────────────────────┘
|
||||
│
|
||||
┌───────────────▼─────────────────────────────┐
|
||||
│ Engine Layer │
|
||||
│ MissionExecutionLoop ←── Scheduler │
|
||||
│ │ │ │
|
||||
│ │ (processTaskOutcome) │ (task:moved│
|
||||
│ ▼ ▼ → done) │
|
||||
│ createKbAgent (validation) MissionAutopilot│
|
||||
│ promptWithFallback │
|
||||
└───────────────┬─────────────────────────────┘
|
||||
│
|
||||
┌───────────────▼─────────────────────────────┐
|
||||
│ Core Layer │
|
||||
│ MissionStore (new methods): │
|
||||
│ startValidatorRun │
|
||||
│ completeValidatorRun │
|
||||
│ recordValidatorFailures │
|
||||
│ createGeneratedFixFeature │
|
||||
│ getFeatureLoopSnapshot │
|
||||
│ SQLite (new tables): │
|
||||
│ mission_validator_runs │
|
||||
│ mission_validator_failures │
|
||||
│ mission_fix_feature_lineage │
|
||||
│ + new columns on mission_features │
|
||||
└─────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────▼─────────────────────────────┐
|
||||
│ Dashboard Layer │
|
||||
│ mission-routes.ts (new endpoints): │
|
||||
│ /assertions CRUD │
|
||||
│ /features/:id/validate │
|
||||
│ /features/:id/validation-loop │
|
||||
│ /validation-runs │
|
||||
│ MissionManager.tsx (new UI): │
|
||||
│ Assertions panel │
|
||||
│ Loop state indicators │
|
||||
│ Validation trigger │
|
||||
│ Run history │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Validation Flow
|
||||
|
||||
1. Feature triaged → task created → task executes → task reaches "done"
|
||||
2. Scheduler detects mission-linked task completion → calls `processTaskOutcome(taskId)`
|
||||
3. MissionExecutionLoop transitions feature: implementing → validating
|
||||
4. Fresh AI agent session created with validation system prompt
|
||||
5. Agent evaluates feature against linked contract assertions
|
||||
6. Agent returns structured JSON: `{ status: pass|fail|blocked, assertions: [...] }`
|
||||
7. Based on result:
|
||||
- **pass**: Feature marked 'passed', autopilot can advance slice
|
||||
- **fail**: Fix feature generated with failure context, retry budget decremented, loop back to implementing
|
||||
- **blocked**: Feature marked 'blocked' (external blocker), no fix generated
|
||||
- **error**: Transient error, feature stays in 'validating' for retry
|
||||
8. If retry budget exhausted: feature permanently 'blocked'
|
||||
|
||||
## Key Invariants
|
||||
|
||||
- Loop state transitions follow a strict state machine (idle → implementing → validating → terminal)
|
||||
- Each validation pass uses a FRESH agent session (no context accumulation)
|
||||
- Retry budget is bounded (default 3 attempts)
|
||||
- All write operations bump `lastModified` for change detection
|
||||
- Cascade deletion flows through the entire chain
|
||||
- Autopilot does NOT advance past features in validating/needs_fix states
|
||||
- Fix features are linked via lineage table for traceability
|
||||
|
||||
## SSE Events (New)
|
||||
|
||||
| Event | Payload | When |
|
||||
|-------|---------|------|
|
||||
| `validator-run:started` | MissionValidatorRun | New run created |
|
||||
| `validator-run:completed` | MissionValidatorRun | Run finished |
|
||||
| `validator-run:failures-recorded` | { runId, failures } | Failures logged |
|
||||
| `fix-feature:created` | { originalFeatureId, fixFeatureId, runId } | Fix generated |
|
||||
| `assertion:created` | MissionContractAssertion | New assertion |
|
||||
| `assertion:updated` | MissionContractAssertion | Assertion modified |
|
||||
| `assertion:deleted` | string | Assertion removed |
|
||||
| `assertion:linked` | { featureId, assertionId } | Feature linked |
|
||||
| `assertion:unlinked` | { featureId, assertionId } | Feature unlinked |
|
||||
| `milestone:validation:updated` | { milestoneId, state, rollup } | Validation state changed |
|
||||
28
.factory/library/environment.md
Normal file
28
.factory/library/environment.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# Environment
|
||||
|
||||
Environment variables, external dependencies, and setup notes.
|
||||
|
||||
**What belongs here:** Required env vars, external API keys/services, dependency quirks, platform-specific notes.
|
||||
**What does NOT belong here:** Service ports/commands (use `.factory/services.yaml`).
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Node.js v25.8.2
|
||||
- pnpm (monorepo workspace)
|
||||
- SQLite (via node:sqlite sync API, WAL mode)
|
||||
- No external services required for this mission
|
||||
|
||||
## AI Provider
|
||||
|
||||
- AI provider is assumed configured (same as existing engine features)
|
||||
- Validation agent sessions use the same `createKbAgent` / `promptWithFallback` API as the executor
|
||||
- Model selection follows existing project settings (defaultProvider/defaultModelId)
|
||||
|
||||
## Testing
|
||||
|
||||
- Unit tests: vitest (`pnpm --filter @fusion/<package> test`)
|
||||
- Type checking: `pnpm build`
|
||||
- E2E tests: mission-e2e.test.ts pattern in dashboard
|
||||
- No external test services needed
|
||||
28
.factory/library/user-testing.md
Normal file
28
.factory/library/user-testing.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# User Testing
|
||||
|
||||
Testing surface, required testing skills/tools, and resource cost classification.
|
||||
|
||||
## Validation Surface
|
||||
|
||||
| Surface | Description | Tool |
|
||||
|---------|-------------|------|
|
||||
| Dashboard UI | Mission manager with assertions panel, loop states, validation controls | agent-browser |
|
||||
| REST API | Assertion CRUD, validation trigger, loop state, runs, recovery | curl |
|
||||
| CLI | Mission commands | Manual verification |
|
||||
|
||||
## Validation Concurrency
|
||||
|
||||
**Machine specs:** 28 CPU cores, 256 GB RAM
|
||||
|
||||
**agent-browser (lightweight app):**
|
||||
- Dashboard is a lightweight web app (~200 MB with dev server)
|
||||
- Each agent-browser instance: ~300 MB RAM
|
||||
- Dev server: ~200 MB
|
||||
- Usable headroom: 256 GB * 0.7 = ~179 GB (very generous)
|
||||
- Max concurrent validators: **5** (standard max)
|
||||
|
||||
## Resource Cost Notes
|
||||
|
||||
- Dashboard dev server (`fn dashboard`) needs to be running for browser tests
|
||||
- API tests via curl are very lightweight — no concurrency limit needed
|
||||
- Tests should use a fresh `.fusion/fusion.db` to avoid state pollution
|
||||
8
.factory/services.yaml
Normal file
8
.factory/services.yaml
Normal file
@@ -0,0 +1,8 @@
|
||||
commands:
|
||||
install: pnpm install
|
||||
build: pnpm build
|
||||
test: pnpm test
|
||||
typecheck: pnpm build
|
||||
lint: pnpm lint
|
||||
|
||||
services: {}
|
||||
90
.factory/skills/backend-worker/SKILL.md
Normal file
90
.factory/skills/backend-worker/SKILL.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: backend-worker
|
||||
description: Backend worker for data model, store, engine, and API implementation
|
||||
---
|
||||
|
||||
# Backend Worker
|
||||
|
||||
NOTE: Startup and cleanup are handled by `worker-base`. This skill defines the WORK PROCEDURE.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Features involving:
|
||||
- Database schema migrations
|
||||
- TypeScript type definitions
|
||||
- MissionStore method implementation
|
||||
- Engine component wiring (MissionExecutionLoop, Scheduler integration)
|
||||
- REST API endpoint implementation
|
||||
- Unit and integration tests for backend code
|
||||
|
||||
## Required Skills
|
||||
|
||||
None.
|
||||
|
||||
## Work Procedure
|
||||
|
||||
1. **Read shared state first.** Read `AGENTS.md`, `.factory/library/architecture.md`, and `.factory/library/environment.md` for context and constraints.
|
||||
|
||||
2. **Understand the feature.** Read the feature description and its `fulfills` assertion IDs from the validation contract. Understand exactly what behavioral assertions must be satisfied.
|
||||
|
||||
3. **Write tests FIRST (TDD).**
|
||||
- For data model work: Write migration tests, type compilation tests, store method tests
|
||||
- For engine work: Write integration tests for wiring, lifecycle, and error handling
|
||||
- For API work: Write route handler tests following patterns in `mission-routes.ts` tests
|
||||
- Tests MUST fail before implementation begins (red → green)
|
||||
|
||||
4. **Implement to make tests pass.**
|
||||
- Follow existing patterns exactly (see AGENTS.md for references)
|
||||
- For schema changes: Edit `packages/core/src/db.ts`, bump version, add migration
|
||||
- For types: Edit `packages/core/src/mission-types.ts`, export from `index.ts`
|
||||
- For store methods: Edit `packages/core/src/mission-store.ts`, follow EventEmitter pattern
|
||||
- For engine wiring: Follow MissionAutopilot pattern exactly
|
||||
- For API routes: Edit `packages/dashboard/src/mission-routes.ts`, follow existing patterns
|
||||
|
||||
5. **Run all tests.** Execute:
|
||||
```
|
||||
pnpm --filter @fusion/core test
|
||||
pnpm --filter @fusion/engine test
|
||||
pnpm --filter @fusion/dashboard test
|
||||
```
|
||||
All must pass. Fix any failures.
|
||||
|
||||
6. **Run type check.** Execute `pnpm build` and ensure no TypeScript errors.
|
||||
|
||||
7. **Manual verification.** If the feature adds API endpoints, verify with curl against a running dashboard. If the feature changes engine wiring, verify startup/shutdown behavior.
|
||||
|
||||
8. **Commit.** One commit per logical step with appropriate message prefix (`feat(FN-XXX):`, `test(FN-XXX):`, etc.).
|
||||
|
||||
## Example Handoff
|
||||
|
||||
```json
|
||||
{
|
||||
"salientSummary": "Implemented mission_validator_runs table schema migration and MissionStore.startValidatorRun/completeValidatorRun methods with full lifecycle tracking, event emission, and cascade deletion support.",
|
||||
"whatWasImplemented": "Schema v31 migration adding mission_validator_runs, mission_validator_failures, and mission_fix_feature_lineage tables plus 7 new columns on mission_features. Added startValidatorRun(), completeValidatorRun(), recordValidatorFailures(), createGeneratedFixFeature(), and getFeatureLoopSnapshot() to MissionStore with events and bumpLastModified.",
|
||||
"whatWasLeftUndone": "",
|
||||
"verification": {
|
||||
"commandsRun": [
|
||||
{"command": "pnpm --filter @fusion/core test", "exitCode": 0, "observation": "All 45 tests passed including 12 new validator run tests"},
|
||||
{"command": "pnpm --filter @fusion/engine test", "exitCode": 0, "observation": "1889 tests passed, no regressions"},
|
||||
{"command": "pnpm build", "exitCode": 0, "observation": "Clean build, no type errors"}
|
||||
],
|
||||
"interactiveChecks": []
|
||||
},
|
||||
"tests": {
|
||||
"added": [
|
||||
{"file": "packages/core/src/mission-store.test.ts", "cases": [
|
||||
{"name": "startValidatorRun creates run with status running", "verifies": "VAL-DM-015"},
|
||||
{"name": "completeValidatorRun transitions to passed", "verifies": "VAL-DM-016"}
|
||||
]}
|
||||
]
|
||||
},
|
||||
"discoveredIssues": []
|
||||
}
|
||||
```
|
||||
|
||||
## When to Return to Orchestrator
|
||||
|
||||
- Feature depends on a type, method, or table that doesn't exist yet and is in another feature's scope
|
||||
- Requirements are ambiguous or contradictory with existing code
|
||||
- Existing bugs in the codebase block this feature
|
||||
- Cannot complete within mission boundaries (ports, services, off-limits areas)
|
||||
95
.factory/skills/frontend-worker/SKILL.md
Normal file
95
.factory/skills/frontend-worker/SKILL.md
Normal file
@@ -0,0 +1,95 @@
|
||||
---
|
||||
name: frontend-worker
|
||||
description: Frontend worker for dashboard UI components, API client functions, and CSS
|
||||
---
|
||||
|
||||
# Frontend Worker
|
||||
|
||||
NOTE: Startup and cleanup are handled by `worker-base`. This skill defines the WORK PROCEDURE.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Features involving:
|
||||
- Dashboard UI components (React)
|
||||
- CSS styling for new UI elements
|
||||
- API client functions in api.ts
|
||||
- Frontend type definitions in mission-types.ts
|
||||
- Component tests
|
||||
|
||||
## Required Skills
|
||||
|
||||
- `agent-browser` — For verifying UI renders correctly and interactions work
|
||||
|
||||
## Work Procedure
|
||||
|
||||
1. **Read shared state first.** Read `AGENTS.md`, `.factory/library/architecture.md`, and `.factory/library/user-testing.md` for context.
|
||||
|
||||
2. **Understand the feature.** Read the feature description and its `fulfills` assertion IDs from the validation contract. Understand exactly what UI behaviors must be verified.
|
||||
|
||||
3. **Update frontend types.** If new types are needed in `packages/dashboard/app/components/mission-types.ts`, add them following existing patterns. Import from the API response shapes.
|
||||
|
||||
4. **Add API client functions.** In `packages/dashboard/app/api.ts`, add functions for any new API endpoints needed by the UI. Follow existing function patterns (return types, error handling).
|
||||
|
||||
5. **Write component tests FIRST (TDD).**
|
||||
- Test rendering of new components
|
||||
- Test user interactions (click handlers, form submissions)
|
||||
- Test empty states and error states
|
||||
- Follow patterns in `MissionManager.test.tsx`
|
||||
|
||||
6. **Implement UI components.**
|
||||
- Add new sections to MissionManager.tsx following existing patterns
|
||||
- Use CSS custom properties for status colors (see existing patterns in styles.css)
|
||||
- Implement inline forms for CRUD (not separate modals)
|
||||
- Add SSE subscription for auto-refresh of loop state and assertions
|
||||
- Ensure mobile responsiveness (375px viewport)
|
||||
|
||||
7. **Verify with agent-browser.** Use the agent-browser skill to:
|
||||
- Navigate to the mission manager
|
||||
- Verify assertions panel renders
|
||||
- Verify loop state indicators display correctly
|
||||
- Verify validation trigger button works
|
||||
- Take screenshots of each state
|
||||
|
||||
8. **Run all tests.**
|
||||
```
|
||||
pnpm --filter @fusion/dashboard test
|
||||
pnpm build
|
||||
```
|
||||
|
||||
9. **Commit.** One commit per logical step.
|
||||
|
||||
## Example Handoff
|
||||
|
||||
```json
|
||||
{
|
||||
"salientSummary": "Added assertions panel to milestone detail view with CRUD operations, feature linking, and status badges. Added loop state visual indicators to feature cards with distinct colors per state.",
|
||||
"whatWasImplemented": "AssertionsPanel section in MissionManager.tsx with create/edit/delete forms, feature link picker, reorder drag-and-drop. Loop state badges on FeatureRow components with CSS animations. API client functions: createAssertion, updateAssertion, deleteAssertion, linkFeatureToAssertion, unlinkFeatureFromAssertion, getFeatureLoopSnapshot.",
|
||||
"whatWasLeftUndone": "",
|
||||
"verification": {
|
||||
"commandsRun": [
|
||||
{"command": "pnpm --filter @fusion/dashboard test", "exitCode": 0, "observation": "All tests passed including 8 new component tests"},
|
||||
{"command": "pnpm build", "exitCode": 0, "observation": "Clean build"}
|
||||
],
|
||||
"interactiveChecks": [
|
||||
{"action": "Navigated to mission manager, opened milestone detail, created assertion", "observed": "Assertion appeared in list with status 'pending' badge"},
|
||||
{"action": "Clicked 'Validate' button on implementing feature", "observed": "Button showed loading spinner, then feature card updated to 'validating' state with yellow indicator"}
|
||||
]
|
||||
},
|
||||
"tests": {
|
||||
"added": [
|
||||
{"file": "packages/dashboard/app/components/__tests__/AssertionsPanel.test.tsx", "cases": [
|
||||
{"name": "renders assertions list", "verifies": "VAL-UI-001"},
|
||||
{"name": "create assertion form submits", "verifies": "VAL-UI-002"}
|
||||
]}
|
||||
]
|
||||
},
|
||||
"discoveredIssues": []
|
||||
}
|
||||
```
|
||||
|
||||
## When to Return to Orchestrator
|
||||
|
||||
- API endpoints the UI needs don't exist yet (backend feature not complete)
|
||||
- Types needed from @fusion/core aren't exported yet
|
||||
- Existing UI patterns are insufficient for the required behavior
|
||||
- Cannot complete within mission boundaries
|
||||
Reference in New Issue
Block a user