Bundle mission-control into Triple-C instead of cloning from GitHub

The mission-control (Flight Control) project is being closed upstream.
This embeds the project files directly in the repo under container/mission-control/,
bakes them into the Docker image at /opt/mission-control, and copies them into place
at container startup instead of git cloning from GitHub.

Also adds missing osc52-clipboard, audio-shim, and triple-c-sso-refresh to the
programmatic Docker build context in image.rs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

container/mission-control/docs/flight-logs.md

@@ -0,0 +1,252 @@
+# Flight Logs
+
+Flight logs are living records created during flight execution. They capture what actually happened—when legs started and ended, what changed, decisions made mid-flight, and any deviations or anomalies encountered.
+
+## What is a Flight Log?
+
+A flight log is the authoritative record of a flight's execution. While the flight document describes the *plan*, the flight log documents *reality*. There is exactly one flight log per flight, updated continuously during execution.
+
+**Important**: Flight logs are **append-only** during execution. Never delete or modify existing entries—only add new ones. This preserves the historical record and ensures nothing is lost when revisiting decisions later.
+
+### Flight Log vs. Other Artifacts
+
+| Artifact | Purpose | When Written | Updates |
+|----------|---------|--------------|---------|
+| Flight | Plan what to do | Before execution | During planning only |
+| Flight Log | Record what happened | During execution | Continuously |
+| Leg | Instructions for one task | Before execution | Never (immutable) |
+
+## Why Flight Logs Matter
+
+### For Current Execution
+
+Flight logs provide:
+- **Continuity**: When work resumes after interruption, the log shows where things stand
+- **Decision history**: Why choices were made when the plan didn't fit reality
+- **Anomaly tracking**: Issues that didn't block progress but need future attention
+
+### For Future Legs
+
+When creating new legs, the flight log reveals:
+- What actually worked vs. what was planned
+- Decisions that affect subsequent implementation
+- Discovered complexity that should inform estimates
+- Patterns or anti-patterns emerging from execution
+
+### For Post-Flight Debrief
+
+The flight log enables meaningful retrospectives by capturing:
+- Actual vs. planned progression
+- Root causes of deviations
+- Learnings that should inform future flights
+
+## Flight Log Structure
+
+```markdown
+# Flight Log: {Flight Title}
+
+## Flight Reference
+[{Flight Title}](flight.md)
+
+## Summary
+Brief overview of the flight's execution status and key outcomes.
+
+---
+
+## Leg Progress
+
+### {Leg Name}
+**Status**: completed | landed | in-flight | aborted
+**Started**: {timestamp}
+**Completed**: {timestamp}
+
+#### Changes Made
+- {Summary of what was implemented}
+- {Files modified and why}
+
+#### Notes
+{Any relevant observations during execution}
+
+---
+
+## Decisions
+
+Choices made during execution that weren't in the original plan.
+
+### {Decision Title}
+**Context**: Why this decision was needed
+**Options Considered**: What alternatives existed
+**Decision**: What was chosen
+**Rationale**: Why this choice was made
+**Impact**: How this affects the flight or future legs
+
+---
+
+## Deviations
+
+Departures from the planned approach.
+
+### {Deviation Title}
+**Planned**: What the flight specified
+**Actual**: What was done instead
+**Reason**: Why the deviation was necessary
+**Outcome**: Result of the deviation
+
+---
+
+## Anomalies
+
+Unexpected issues or behaviors encountered.
+
+### {Anomaly Title}
+**Observed**: What happened
+**Expected**: What should have happened
+**Severity**: blocking | degraded | cosmetic
+**Resolution**: How it was handled (or "unresolved")
+**Follow-up**: Any actions needed later
+
+---
+
+## Session Notes
+
+Chronological notes from each work session.
+
+### {Date/Session Identifier}
+- {Note about progress or observation}
+- {Note about what was attempted}
+- {Note about what was learned}
+```
+
+## When to Update the Flight Log
+
+### Starting a Leg
+
+Record:
+- Leg name and start timestamp
+- Any context carried from previous legs
+- Initial observations about the task
+
+### During Execution
+
+Record:
+- Decisions that diverge from or extend the plan
+- Unexpected complexity or simplicity
+- Anomalies encountered (even if resolved)
+
+### Completing a Leg
+
+Record:
+- Completion timestamp
+- Summary of changes made
+- Files modified
+- Any notes for future legs
+
+### Encountering Issues
+
+Record immediately:
+- What went wrong
+- What was expected
+- Severity and impact
+- Resolution or workaround
+
+## Using Flight Logs When Creating Legs
+
+When generating new legs with `/leg`, the flight log must be consulted to understand:
+
+1. **What's actually complete**: The log shows real completion status, not just planned progress
+2. **Decisions made**: Mid-flight decisions may change how subsequent legs should be implemented
+3. **Discovered context**: Anomalies and deviations reveal system behavior that affects new work
+4. **Patterns established**: Implementation approaches that worked (or didn't) inform future guidance
+
+### Example: Log Informing Leg Creation
+
+**Flight log entry:**
+```markdown
+### API Authentication Leg
+**Status**: completed
+
+#### Changes Made
+- Implemented JWT auth in `src/middleware/auth.ts`
+- Used `jose` library instead of planned `jsonwebtoken` (see Decisions)
+
+#### Decisions
+**JWT Library Change**
+- Context: `jsonwebtoken` had CVE flagged in security scan
+- Decision: Switch to `jose` library
+- Impact: All subsequent auth-related code must use `jose` patterns
+```
+
+**Impact on next leg:**
+When creating the "Protected Routes" leg, the guidance must specify using `jose` patterns, not the originally planned `jsonwebtoken` approach. Without the flight log, this context would be lost.
+
+## Location
+
+Flight log location is defined in `.flightops/ARTIFACTS.md`. The artifact system determines where and how logs are stored.
+
+## Best Practices
+
+### Keep Entries Atomic
+
+Write entries as things happen, not in batches. Batched entries lose detail and context.
+
+### Be Factual, Not Editorial
+
+**Good**: "Validation logic required 3 additional edge cases not in spec"
+**Avoid**: "The spec was incomplete and caused problems"
+
+### Link to Specifics
+
+Reference file paths, line numbers, commit hashes when relevant. Vague entries lose value quickly.
+
+### Capture the "Why"
+
+The code shows *what* changed. The log should capture *why* decisions were made.
+
+### Don't Duplicate the Leg
+
+The leg document has acceptance criteria and implementation guidance. The log records completion status and what actually happened—not a copy of the plan.
+
+## Common Patterns
+
+### Discovery Pattern
+
+When execution reveals something unexpected:
+
+```markdown
+### Discovery: Rate Limiting Already Exists
+**Observed**: Found existing rate limiter in `src/middleware/rateLimit.ts`
+**Expected**: Needed to implement from scratch per flight spec
+**Impact**: Leg `implement-rate-limiting` can be simplified to configuration
+**Action**: Updated leg scope, reduced from 4 hours to 30 minutes
+```
+
+### Blocker Pattern
+
+When progress stops:
+
+```markdown
+### Blocker: Missing API Credentials
+**Observed**: Stripe API key not in environment
+**Severity**: blocking
+**Impact**: Cannot test payment integration
+**Resolution**: Requested credentials from DevOps
+**Unblocked**: {timestamp when resolved}
+```
+
+### Adaptation Pattern
+
+When the plan needs adjustment:
+
+```markdown
+### Deviation: Schema Change
+**Planned**: Add `verified` boolean to User model
+**Actual**: Added `verifiedAt` timestamp instead
+**Reason**: Team decided verification time is valuable data
+**Outcome**: Provides more information, minor query adjustments needed
+```
+
+## Next Steps
+
+- [Flights](flights.md) — Understanding flight structure and lifecycle
+- [Legs](legs.md) — How legs are created and executed
+- [Workflow](workflow.md) — The complete flow from mission to completion

container/mission-control/docs/flights.md

@@ -0,0 +1,462 @@
+# Flights
+
+Flights are the balanced layer of Flight Control—technical enough for implementation, readable enough for humans. A flight and its flight plan are synonymous: the document *is* the plan.
+
+## What is a Flight?
+
+A flight translates mission outcomes into technical specifications. Flights are:
+
+- **Technically scoped**: Bounded implementation work
+- **Checklist-driven**: Pre-flight, in-flight, and post-flight phases
+- **Adaptive**: Living documents that evolve with understanding
+
+### Flight vs. Mission vs. Leg
+
+| Aspect | Mission | Flight | Leg |
+|--------|---------|--------|-----|
+| Question | Why? | What & How? | Do this |
+| Audience | Stakeholders | Developers/AI | AI agents |
+| Flexibility | High | Medium | Low |
+| Updates | Rarely | As needed | Never (create new) |
+
+## Flight Structure
+
+Every flight has three sections corresponding to its lifecycle:
+
+```markdown
+# Flight: {Title}
+
+## Mission Link
+Parent mission and relevant success criteria.
+
+---
+
+## Pre-Flight
+
+### Objective
+What this flight accomplishes.
+
+### Open Questions
+- [ ] Question needing resolution
+- [ ] Another question
+
+### Design Decisions
+Choices made and their rationale.
+
+### Prerequisites
+What must be true before execution begins.
+
+### Pre-Flight Checklist
+- [ ] Questions resolved
+- [ ] Design decisions documented
+- [ ] Prerequisites verified
+- [ ] Legs defined
+
+---
+
+## In-Flight
+
+### Technical Approach
+How the objective will be achieved.
+
+### Checkpoints
+Key milestones during execution.
+
+### Adaptation Criteria
+When to deviate from plan.
+
+### Legs
+Links to implementation legs.
+
+---
+
+## Post-Flight
+
+### Completion Checklist
+- [ ] All legs completed
+- [ ] Integration verified
+- [ ] Tests passing
+- [ ] Documentation updated
+
+### Verification
+How to confirm the flight achieved its objective.
+
+### Retrospective Notes
+What was learned during this flight.
+```
+
+## Pre-Flight Phase
+
+Pre-flight is about readiness. No implementation happens here—only planning.
+
+### Open Questions
+
+Capture unknowns that need resolution before execution:
+
+```markdown
+### Open Questions
+- [ ] Should we use JWT or session-based auth?
+- [ ] What OAuth providers do we need to support?
+- [ ] How long should sessions remain valid?
+```
+
+Questions should be:
+- **Specific**: Clear what information is needed
+- **Blocking**: Execution can't proceed without answers
+- **Resolvable**: Someone can answer them
+
+Check off questions as they're resolved and document answers in Design Decisions.
+
+### Design Decisions
+
+Record choices and rationale:
+
+```markdown
+### Design Decisions
+
+**Authentication Method**: JWT tokens
+- Rationale: Stateless, works across services
+- Trade-off: Token revocation more complex
+- Decided by: Security team review
+
+**Session Duration**: 7 days with refresh
+- Rationale: Balance security and convenience
+- Trade-off: Longer exposure window
+- Decided by: Product requirements
+```
+
+Design decisions prevent relitigating settled questions and help future maintainers understand *why*.
+
+### Prerequisites
+
+List conditions required for execution:
+
+```markdown
+### Prerequisites
+- [ ] Database schema migrations ready
+- [ ] API authentication middleware exists
+- [ ] Test environment configured
+- [ ] Security review of approach completed
+```
+
+Prerequisites are external dependencies. If they're not met, the flight can't begin safely.
+
+### Pre-Flight Checklist
+
+The gate check before execution:
+
+```markdown
+### Pre-Flight Checklist
+- [ ] All open questions resolved
+- [ ] Design decisions documented with rationale
+- [ ] Prerequisites verified
+- [ ] Legs defined with acceptance criteria
+- [ ] Estimated scope is reasonable
+```
+
+When all items are checked, the flight moves from `planning` to `ready`.
+
+## Flight Briefing
+
+Before execution begins, create a **flight briefing** to align the crew:
+
+```markdown
+# Flight Briefing: {Title}
+
+## Mission Context
+How this flight contributes to the mission.
+
+## Objective
+What this flight will accomplish.
+
+## Key Decisions
+Critical design decisions the crew should know.
+
+## Risks
+Known risks and mitigation strategies.
+
+## Legs Overview
+Summary of legs with complexity notes.
+
+## Success Criteria
+How we'll know the flight succeeded.
+```
+
+The briefing is created when the flight moves to `ready` status.
+
+## In-Flight Phase
+
+In-flight is execution. Legs are being worked, progress is tracked in the [flight log](flight-logs.md).
+
+### Technical Approach
+
+Document *how* the objective will be achieved:
+
+```markdown
+### Technical Approach
+
+1. Create user model with email/password fields
+2. Implement registration endpoint with validation
+3. Add login endpoint with JWT generation
+4. Create middleware for protected routes
+5. Add password reset flow
+```
+
+This bridges design decisions to concrete implementation without being leg-level specific.
+
+### Checkpoints
+
+Define milestones for progress tracking:
+
+```markdown
+### Checkpoints
+- [ ] User registration working end-to-end
+- [ ] Login returning valid tokens
+- [ ] Protected routes rejecting invalid tokens
+- [ ] Password reset emails sending
+```
+
+Checkpoints help identify if a flight is on track or needs intervention.
+
+### Adaptation Criteria
+
+When should the plan change?
+
+```markdown
+### Adaptation Criteria
+
+**Divert if**:
+- Security vulnerability discovered in approach
+- External API changes break integration
+- Performance testing reveals blocking issues
+
+**Acceptable variations**:
+- Minor API changes for developer experience
+- Additional validation rules
+- Extended error handling
+```
+
+Explicit adaptation criteria prevent both rigid adherence to bad plans and unnecessary scope creep.
+
+### Legs
+
+Reference the implementation legs:
+
+```markdown
+### Legs
+- [x] `create-user-model` - completed
+- [x] `registration-endpoint` - completed
+- [ ] `login-endpoint` - in-flight
+- [ ] `auth-middleware` - planning
+- [ ] `password-reset` - planning
+```
+
+### Flight Log
+
+During execution, maintain a [flight log](flight-logs.md) alongside this document. The flight log records:
+
+- **Leg progress**: When legs start and complete, with summaries of changes
+- **Decisions**: Choices made during execution not in the original plan
+- **Deviations**: Departures from the planned approach and why
+- **Anomalies**: Unexpected issues or behaviors encountered
+
+The flight log is essential for:
+- Providing continuity when work resumes after interruption
+- Informing the creation of subsequent legs
+- Enabling meaningful post-flight retrospectives
+
+## Post-Flight Phase
+
+Post-flight is verification and learning. Implementation is complete; now confirm success.
+
+### Completion Checklist
+
+Verify all work is finished:
+
+```markdown
+### Completion Checklist
+- [ ] All legs marked completed
+- [ ] Code merged to main branch
+- [ ] Integration tests passing
+- [ ] Documentation updated
+- [ ] No blocking issues remaining
+```
+
+### Verification
+
+How to confirm the flight succeeded:
+
+```markdown
+### Verification
+
+**Manual verification**:
+1. Create new user account
+2. Log in with credentials
+3. Access protected endpoint
+4. Log out and verify token invalid
+
+**Automated verification**:
+- `npm run test:auth` passes
+- `npm run test:e2e` auth flows pass
+```
+
+### Retrospective Notes
+
+Capture learnings for future flights:
+
+```markdown
+### Retrospective Notes
+
+**What went well**:
+- JWT library well-documented
+- Security review caught edge case early
+
+**What could improve**:
+- Underestimated password reset complexity
+- Should have spiked OAuth earlier
+
+**For next time**:
+- Include OAuth research in pre-flight
+- Add explicit leg for error handling
+```
+
+## Flight Lifecycle
+
+Flights progress through defined states:
+
+### States
+
+```
+planning ──► ready ──► in-flight ──► landed ──► completed
+                           │
+                           └──► aborted
+```
+
+**planning**
+Pre-flight phase. Questions being resolved, design decisions being made.
+
+**ready**
+Pre-flight checklist complete. All prerequisites met. Ready to execute.
+
+**in-flight**
+Legs actively being executed. Checkpoints being reached. Flights may be modified during this phase (e.g., changing planned legs) as long as the flight log captures the change and rationale.
+
+**landed**
+All legs complete. Verification passed. Flight achieved its objective. Ready for debrief.
+
+**completed**
+Debrief done. Flight fully wrapped up and artifacts updated.
+
+**aborted**
+Flight cancelled. Changes are rolled back. Document the reason for future reference.
+
+### In-Flight Modifications
+
+Flights can be modified while `in-flight` — for example, when planned legs need to change due to discoveries during execution. This is not a separate state; simply update the flight artifact and record the change and rationale in the flight log.
+
+**Create a new flight when:**
+- A completely new objective emerges
+- The discovered work is independent of the current flight's goal
+- The new work serves different mission success criteria
+
+### State Transitions
+
+| From | To | Trigger |
+|------|----|---------|
+| planning | ready | Pre-flight checklist complete |
+| ready | in-flight | First leg begins |
+| in-flight | landed | All legs complete |
+| in-flight | aborted | Flight cancelled, changes rolled back |
+| landed | completed | Debrief complete |
+
+## Connecting to Parent Mission
+
+Flights serve missions. Each flight should clearly link to:
+
+```markdown
+## Mission Link
+
+**Mission**: [Secure User Authentication](../mission.md)
+
+**Contributing to criteria**:
+- [ ] Users can create accounts with email/password
+- [ ] Session management handles concurrent logins
+```
+
+This traceability ensures flights aren't orphaned work—they connect to meaningful outcomes.
+
+## Connecting to Child Legs
+
+Flights generate legs. The flight defines *what* needs to happen; legs define the *exact* implementation steps.
+
+A well-structured flight enables AI agents to execute legs without needing clarification:
+
+**Flight provides**:
+- Technical approach and patterns
+- Design decisions and constraints
+- Context about the broader system
+
+**Legs consume**:
+- Specific task to complete
+- Acceptance criteria to meet
+- Context from flight document
+
+## Common Pitfalls
+
+### Skipping Pre-Flight
+
+Rushing to implementation creates problems. Pre-flight exists to:
+- Surface hidden complexity
+- Align on approach before work begins
+- Identify blocking dependencies
+
+A thorough pre-flight prevents mid-flight crises.
+
+### Over-Specifying
+
+Flights should guide, not constrain. Leave room for:
+- Implementation details discovered during work
+- Better approaches found during execution
+- Minor adjustments that don't affect outcomes
+
+### Ignoring Adaptation Criteria
+
+When circumstances change, adapt the plan. Flights that ignore reality become fiction. Use adaptation criteria to decide when to divert.
+
+### Skipping Post-Flight
+
+Post-flight isn't bureaucracy—it's learning. Retrospective notes prevent repeating mistakes. Verification confirms the flight actually succeeded.
+
+## Flight Debrief
+
+After a flight lands (or diverts), create a **flight debrief** for retrospective analysis:
+
+```markdown
+# Flight Debrief: {Title}
+
+## Outcome Assessment
+What the flight accomplished and which mission criteria it advanced.
+
+## What Went Well
+Effective patterns during execution.
+
+## What Could Be Improved
+Process and technical recommendations.
+
+## Deviations and Lessons
+What changed from the plan and why.
+
+## Recommendations
+Top 3-5 most impactful improvements.
+
+## Action Items
+Follow-up work and improvements.
+```
+
+The debrief enables continuous improvement and informs future flights.
+
+## Next Steps
+
+- [Flight Logs](flight-logs.md) — Recording execution progress and decisions
+- [Legs](legs.md) — Learn to write AI-optimized implementation steps
+- [Workflow](workflow.md) — See how flights flow into legs

container/mission-control/docs/legs.md

@@ -0,0 +1,383 @@
+# Legs
+
+Legs are the AI-optimized layer of Flight Control. They provide structured, explicit instructions that AI agents can execute without ambiguity.
+
+## What is a Leg?
+
+A leg is a single, atomic unit of implementation work. Legs are:
+
+- **Explicit**: No ambiguity about what "done" means
+- **Bounded**: Clear start and end points
+- **Context-complete**: All necessary information included
+- **AI-consumable**: Structured for machine parsing
+
+### Leg vs. Flight vs. Mission
+
+| Aspect | Mission | Flight | Leg |
+|--------|---------|--------|-----|
+| Scope | Outcome | Feature | Task |
+| Duration | Days-weeks | Hours-days | Minutes-hours |
+| Modifications | Allowed | Allowed | Create new instead |
+| Audience | Humans | Developers/AI | AI agents |
+
+## Leg Structure
+
+Legs follow a consistent structure optimized for AI consumption:
+
+```markdown
+# Leg: {slug}
+
+## Flight Link
+[Parent flight](../flight.md)
+
+## Objective
+Single sentence describing what this leg accomplishes.
+
+## Context
+Information the AI needs to understand this task.
+
+## Inputs
+- What exists before this leg runs
+
+## Outputs
+- What exists after this leg completes
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Verification Steps
+How to confirm each criterion is met (commands, manual checks, tools).
+
+## Implementation Guidance
+Specific patterns, approaches, or constraints.
+
+## Files Likely Affected
+- `path/to/file.ts`
+- `path/to/test.ts`
+```
+
+## Writing Effective Legs
+
+### Objectives
+
+State exactly what the leg accomplishes in one sentence:
+
+**Weak**:
+> Set up the user stuff
+
+**Strong**:
+> Create the User model with email, password_hash, and timestamps fields
+
+The objective should be:
+- **Specific**: Clear what will be created/modified
+- **Verifiable**: Can confirm completion by inspection
+- **Atomic**: One cohesive piece of work
+
+### Context
+
+Provide information the AI needs but might not have:
+
+```markdown
+## Context
+
+This project uses Prisma for database access. The existing `prisma/schema.prisma`
+file contains the Post and Comment models. User will be referenced by these
+models via foreign keys.
+
+Authentication uses JWT tokens. The password_hash field will store bcrypt hashes
+(cost factor 12). The email field must be unique and will be used as the login
+identifier.
+```
+
+Good context includes:
+- Relevant technology/framework information
+- Relationship to existing code
+- Design decisions from the parent flight
+- Constraints that affect implementation
+
+### Inputs and Outputs
+
+Be explicit about state before and after:
+
+```markdown
+## Inputs
+- Prisma schema at `prisma/schema.prisma` with Post and Comment models
+- No existing User model or authentication
+
+## Outputs
+- User model added to Prisma schema
+- Migration file generated
+- Migration applied to development database
+```
+
+Inputs help the AI understand starting conditions. Outputs define the expected end state.
+
+### Acceptance Criteria
+
+Define exactly what "done" means:
+
+```markdown
+## Acceptance Criteria
+- [ ] User model exists in `prisma/schema.prisma`
+- [ ] User model has fields: id, email, password_hash, created_at, updated_at
+- [ ] email field has `@unique` attribute
+- [ ] Migration file exists in `prisma/migrations/`
+- [ ] `npx prisma migrate status` shows no pending migrations
+- [ ] TypeScript types generated (`npx prisma generate` succeeds)
+```
+
+Acceptance criteria should be:
+- **Binary**: Either met or not met
+- **Observable**: Can verify by inspection or test
+- **Complete**: Nothing else required for "done"
+
+### Verification Steps
+
+Tell the AI exactly *how* to confirm each criterion:
+
+```markdown
+## Verification Steps
+- Run `npx prisma migrate status` — should show no pending migrations
+- Run `npm test` — all tests pass
+- Open browser to `/users` — page loads without errors
+- Tab through form fields — focus order matches visual order
+- Run `npx lighthouse --accessibility` — score ≥ 90
+```
+
+Verification steps should be:
+- **Executable**: Commands or specific actions
+- **Deterministic**: Same result every time
+- **Mapped to criteria**: Clear which criterion each step validates
+
+For accessibility legs, include specific checks:
+- Keyboard navigation sequences to test
+- Screen reader commands (e.g., "navigate to main content via skip link")
+- Automated tool commands (Lighthouse, axe-core)
+
+### Implementation Guidance
+
+Provide specific direction when needed:
+
+```markdown
+## Implementation Guidance
+
+Use Prisma's native type for id:
+```prisma
+id String @id @default(cuid())
+```
+
+For timestamps, use Prisma's auto-managed fields:
+```prisma
+created_at DateTime @default(now())
+updated_at DateTime @updatedAt
+```
+
+Do not add relations to Post/Comment yet—that's a separate leg.
+```
+
+Implementation guidance helps when:
+- Project has specific patterns to follow
+- There are multiple valid approaches (pick one)
+- Constraints aren't obvious from context
+
+### Files Likely Affected
+
+Help the AI know where to look:
+
+```markdown
+## Files Likely Affected
+- `prisma/schema.prisma` - Add User model
+- `prisma/migrations/*` - New migration file (generated)
+```
+
+This isn't prescriptive—the AI might touch other files. It's a starting point for orientation.
+
+## Leg Lifecycle
+
+Legs progress through defined states:
+
+### States
+
+```
+planning ──► ready ──► in-flight ──► landed ──► completed
+                           │
+                           └──► aborted
+```
+
+**planning**
+Leg is being designed. Acceptance criteria and implementation guidance being defined.
+
+**ready**
+Leg design approved. Ready for implementation.
+
+**in-flight**
+AI agent actively working on implementation.
+
+**landed**
+Implementation complete. Flight log updated. Ready for review.
+
+**completed**
+Review passed. Acceptance criteria confirmed met.
+
+**aborted**
+Leg cancelled. Changes are rolled back. Document the reason in the flight log.
+
+### State Transitions
+
+| From | To | Trigger |
+|------|----|---------|
+| planning | ready | Design review passes |
+| ready | in-flight | Developer begins work |
+| in-flight | landed | Developer reports completion |
+| in-flight | aborted | Cannot proceed, changes rolled back |
+| landed | completed | Review passes |
+| landed | in-flight | Issues found, needs fixes |
+
+Note: Legs may only be modified while in `planning` state. Once `in-flight`, create new legs instead of modifying existing ones.
+
+## Patterns for AI Consumption
+
+### Be Explicit, Not Implicit
+
+**Implicit** (requires inference):
+> Add validation to the email field
+
+**Explicit** (no inference needed):
+> Add email validation: must be non-empty, valid email format (use validator library's isEmail), maximum 255 characters. Return 400 status with `{ error: "Invalid email format" }` on failure.
+
+### Provide Examples
+
+When patterns might be unclear, show don't tell:
+
+```markdown
+## Implementation Guidance
+
+Follow the existing controller pattern:
+
+```typescript
+// Example from PostController
+export async function createPost(req: Request, res: Response) {
+  const { title, content } = req.body;
+
+  if (!title) {
+    return res.status(400).json({ error: "Title is required" });
+  }
+
+  const post = await prisma.post.create({
+    data: { title, content, authorId: req.user.id }
+  });
+
+  return res.status(201).json(post);
+}
+```
+
+Apply this pattern to the registration endpoint.
+```
+
+### State Constraints Clearly
+
+Don't bury constraints in prose:
+
+**Buried**:
+> Create the endpoint and make sure it handles errors properly and validates input and also we're using Express and the response should be JSON.
+
+**Clear**:
+```markdown
+## Constraints
+- Framework: Express.js
+- Response format: JSON
+- Error handling: Return appropriate HTTP status codes
+- Validation: Validate all input before processing
+```
+
+### Link to Flight for Context
+
+When details would be redundant, reference the parent:
+
+```markdown
+## Context
+
+See [parent flight](../flight.md) for:
+- Authentication approach (JWT tokens)
+- Session duration decisions
+- Error response format standards
+```
+
+## Common Pitfalls
+
+### Too Large
+
+If a leg takes more than a few hours, it's probably too big. Signs:
+- Multiple independent pieces of functionality
+- Would benefit from intermediate checkpoints
+- Hard to write clear acceptance criteria
+
+Split into smaller legs.
+
+### Too Small
+
+If a leg is trivial, it adds overhead without value. Signs:
+- Single line change
+- No meaningful acceptance criteria
+- Part of a larger atomic operation
+
+Combine with related work.
+
+### Ambiguous Acceptance Criteria
+
+If criteria require judgment, they're not criteria:
+
+**Ambiguous**: "Code is clean and readable"
+**Specific**: "Functions are under 50 lines, no eslint warnings"
+
+**Ambiguous**: "Error handling is good"
+**Specific**: "All async operations wrapped in try/catch, errors logged with context"
+
+### Missing Context
+
+AI agents don't have your mental model. Include:
+- Why this approach (from flight decisions)
+- How this fits with existing code
+- What patterns to follow
+- What to avoid
+
+## Relationship to Flight
+
+Legs are generated from flights. The flight provides:
+- Technical approach
+- Design decisions
+- Overall context
+
+Legs provide:
+- Specific implementation steps
+- Explicit acceptance criteria
+- Focused scope
+
+A flight might generate many legs:
+
+```
+Flight: User Registration Flow
+├── Leg: create-user-model
+├── Leg: registration-endpoint
+├── Leg: email-validation
+├── Leg: password-hashing
+├── Leg: registration-tests
+└── Leg: registration-docs
+```
+
+## Immutability Principle
+
+Once a leg is `in-flight`, don't modify it. If requirements change:
+
+1. Mark the current leg as aborted (changes rolled back)
+2. Create a new leg with updated requirements
+3. Reference the old leg for context
+
+This preserves history and prevents confusion about what the AI was asked to do.
+
+## Next Steps
+
+- [Workflow](workflow.md) — See the complete mission → flight → leg flow
+- [Flights](flights.md) — Understand where legs come from

container/mission-control/docs/missions.md

@@ -0,0 +1,245 @@
+# Missions
+
+Missions are the human-optimized layer of Flight Control. They define *what* success looks like without prescribing *how* to achieve it.
+
+## What is a Mission?
+
+A mission represents a meaningful outcome—something a stakeholder would recognize as valuable. Missions are:
+
+- **Outcome-driven**: Focused on results, not activities
+- **Human-readable**: Written for people, not machines
+- **Strategically scoped**: Large enough to matter, bounded enough to complete
+
+### Mission vs. Flight vs. Leg
+
+| Aspect | Mission | Flight | Leg |
+|--------|---------|--------|-----|
+| Audience | Humans, stakeholders | Developers, AI | AI agents |
+| Scope | Outcome | Technical spec | Single task |
+| Style | Narrative | Structured | Explicit |
+| Duration | Days to weeks | Hours to days | Minutes to hours |
+
+## Writing Effective Missions
+
+### Start with Outcomes
+
+Frame missions around what changes when they're complete:
+
+**Weak** (activity-focused):
+> Implement user authentication
+
+**Strong** (outcome-focused):
+> Users can securely access their personal data without sharing credentials across services
+
+The outcome framing:
+- Clarifies *why* the work matters
+- Leaves implementation decisions to flights
+- Provides a clear test for completion
+
+### Define Success Criteria
+
+Every mission needs measurable success criteria. These answer: "How do we know we're done?"
+
+```markdown
+## Success Criteria
+
+- [ ] Users can create accounts with email/password
+- [ ] Users can authenticate via OAuth providers
+- [ ] Session management handles concurrent logins
+- [ ] Security audit passes with no critical findings
+```
+
+Success criteria should be:
+- **Observable**: Can be verified by inspection
+- **Binary**: Either met or not met
+- **Independent**: Achievable without external dependencies
+- **Capability-focused**: Describes what users or the system can do, not which tool or technology achieves it
+
+### Consider Stakeholders
+
+Missions serve stakeholders. Identify them explicitly:
+
+```markdown
+## Stakeholders
+
+- **End users**: Need frictionless, secure access
+- **Security team**: Requires compliance with auth standards
+- **Support team**: Needs ability to assist locked-out users
+```
+
+Stakeholder identification helps:
+- Prioritize competing concerns
+- Identify missing success criteria
+- Communicate progress meaningfully
+
+## Mission Structure
+
+A mission document typically contains:
+
+```markdown
+# Mission: {Title}
+
+## Outcome
+What success looks like in human terms.
+
+## Context
+Why this mission matters now. Background information.
+
+## Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Stakeholders
+Who cares about this outcome and why.
+
+## Constraints
+Non-negotiable boundaries (budget, timeline, technology).
+
+## Environment Requirements
+Development environment, runtime dependencies, special tooling.
+
+## Open Questions
+Unknowns that need resolution during execution.
+
+## Known Issues
+Emergent blockers and issues discovered during execution.
+
+## Flights
+Links to flights executing this mission.
+```
+
+## Mission Lifecycle
+
+Missions progress through defined states:
+
+### States
+
+```
+planning ──► active ──► completed
+                │
+                └──► aborted
+```
+
+**planning**
+The mission is being defined. Outcome, success criteria, and constraints are still being refined. No flights have started.
+
+**active**
+At least one flight is in progress. The mission outcome is being pursued. New flights may be created as understanding develops.
+
+**completed**
+All success criteria are met. Stakeholders have accepted the outcome. The mission can be archived.
+
+**aborted**
+The mission was cancelled before completion. This might happen due to:
+- Changed priorities
+- Discovered infeasibility
+- External factors
+
+Aborted missions should document *why* they were cancelled for future reference.
+
+### State Transitions
+
+| From | To | Trigger |
+|------|----|---------|
+| planning | active | First flight begins |
+| active | completed | All success criteria met |
+| active | aborted | Cancellation decision |
+| planning | aborted | Cancellation decision |
+
+## Communicating Mission Status
+
+Missions are stakeholder-facing. Status updates should be meaningful to non-technical audiences:
+
+**Weak update**:
+> Completed 3 of 5 flights
+
+**Strong update**:
+> Users can now create accounts and log in. Next: adding OAuth support and security review.
+
+Link progress to outcomes, not activities.
+
+## Common Pitfalls
+
+### Too Granular
+
+If a mission can be completed in a single flight, it's probably too small. Consider:
+- Is this a meaningful outcome or just a task?
+- Would a stakeholder recognize this as valuable?
+- Does it warrant its own success criteria?
+
+### Too Vague
+
+Missions need boundaries. "Improve the product" isn't a mission—it's a direction. Missions should be:
+- Completable (has an end state)
+- Measurable (success criteria exist)
+- Bounded (scope is clear)
+
+### Implementation Leaking In
+
+Missions should not prescribe *how*:
+
+**Leaking implementation**:
+> Build a React-based authentication flow using JWT tokens stored in HttpOnly cookies
+
+**Proper abstraction**:
+> Users can securely authenticate across sessions without re-entering credentials
+
+This applies to success criteria too. Criteria that name tools or technologies lock you into an approach before flights even begin:
+
+**Implementation-specific criteria** (avoid):
+> - [ ] JWT tokens are validated via middleware on every request
+> - [ ] User records are stored in PostgreSQL with bcrypt-hashed passwords
+
+**Capability-focused criteria** (prefer):
+> - [ ] Unauthorized requests are rejected before reaching protected resources
+> - [ ] Stored credentials cannot be recovered even if the database is compromised
+
+Save implementation details for flights.
+
+## Mission Debrief
+
+After a mission completes (or aborts), create a **mission debrief** for retrospective learning:
+
+```markdown
+# Mission Debrief: {Title}
+
+## Success Criteria Results
+Which criteria were met, partially met, or not met.
+
+## Flight Summary
+Overview of how each flight contributed.
+
+## What Went Well
+Effective patterns and successes.
+
+## What Could Be Improved
+Process and execution improvements.
+
+## Lessons Learned
+Insights to carry forward.
+
+## Methodology Feedback
+Improvements to Flight Control itself.
+```
+
+The debrief captures organizational learning and informs future missions.
+
+## Relationship to Flights
+
+Missions spawn flights. A typical mission might have:
+
+```
+Mission: Secure User Authentication
+├── Flight: Account creation flow
+├── Flight: Login and session management
+├── Flight: OAuth integration
+└── Flight: Security hardening
+```
+
+Flights can be planned upfront or emerge as the mission progresses. The mission provides the "why"; flights provide the "what" and "how".
+
+## Next Steps
+
+- [Flights](flights.md) — Learn to create technical specifications
+- [Workflow](workflow.md) — See how missions flow into flights

container/mission-control/docs/overview.md

@@ -0,0 +1,136 @@
+# Flight Control Overview
+
+Flight Control is a methodology for AI-first software development that maintains meaningful human oversight while maximizing AI effectiveness.
+
+## Philosophy
+
+### AI-First, Human-Guided
+
+Traditional development methodologies were designed for human developers. They assume humans will interpret requirements, make design decisions, and adapt to changing circumstances. AI agents work differently—they excel with explicit structure but struggle with ambiguity.
+
+Flight Control inverts the traditional approach:
+
+- **Humans define outcomes**, not implementation details
+- **AI executes implementations**, not strategic decisions
+- **The methodology bridges the gap** through progressive specification
+
+### Why Aviation Works
+
+Aviation provides a proven model for high-stakes operations where planning and execution are separate concerns:
+
+| Aviation | Flight Control |
+|----------|----------------|
+| Mission objectives | Mission outcomes |
+| Flight plan | Flight specification |
+| Flight legs | Implementation legs |
+| Pilot authority | Human oversight |
+| Autopilot execution | AI execution |
+
+The key insight: pilots don't recompute routes in real-time. They follow pre-computed flight plans while retaining authority to adapt when circumstances demand. Similarly, AI agents shouldn't reinvent architecture with each task—they should execute well-specified legs while flagging issues for human review.
+
+## Key Principles
+
+### 1. Outcome-Driven Planning
+
+Missions start with outcomes, not tasks:
+
+**Traditional**: "Build a user authentication system"
+**Flight Control**: "Users can securely access their accounts with minimal friction"
+
+The outcome framing keeps focus on what matters while leaving implementation flexible.
+
+### 2. Adaptive Specifications
+
+Flights are living documents. Unlike traditional specs that become stale, flight plans explicitly track:
+
+- Open questions requiring resolution
+- Design decisions and their rationale
+- Prerequisites and dependencies
+- Adaptation criteria (when to deviate from plan)
+
+### 3. Structured Execution
+
+Legs are optimized for AI consumption:
+
+- Explicit acceptance criteria
+- Required context clearly stated
+- Expected inputs and outputs defined
+- No ambiguity in scope
+
+### 4. Layered Feedback
+
+Information flows both directions:
+
+- **Downward**: Missions inform flights, flights generate legs
+- **Upward**: Leg completion updates flights, flight outcomes inform mission status
+
+## Comparison to Traditional Methodologies
+
+### vs. Agile/Scrum
+
+Agile emphasizes iterative human collaboration. Flight Control complements this by structuring how AI fits into iterations:
+
+- Sprints can contain multiple flights
+- Stories map roughly to flights
+- Tasks map to legs
+
+Flight Control adds the missing layer: how to specify work for AI execution.
+
+### vs. Waterfall
+
+Waterfall assumes complete upfront specification. Flight Control embraces uncertainty:
+
+- Missions can spawn new flights as understanding evolves
+- Flights can be modified in-flight when circumstances change
+- Legs can be aborted and replaced
+
+### vs. CRISP-DM / ML Workflows
+
+Data science workflows focus on experimentation. Flight Control adds structure without eliminating iteration:
+
+- Experimental flights can have "explore" legs
+- Failed experiments inform mission outcomes
+- Reproducibility is built into leg specifications
+
+## The Audience Gradient
+
+A core innovation is the **audience gradient**—documentation shifts style based on who consumes it:
+
+```
+Human Readable ◄─────────────────────────────► AI Optimized
+     │                    │                         │
+  Mission              Flight                      Leg
+     │                    │                         │
+ Narrative prose    Technical spec          Structured format
+ Outcome-focused    Checklist-driven        Explicit criteria
+ Flexible scope     Bounded scope           Fixed scope
+```
+
+This gradient acknowledges that humans and AI have different strengths:
+
+- Humans excel at ambiguity, context, and strategic thinking
+- AI excels at following explicit instructions consistently
+
+Flight Control puts each audience where they're strongest.
+
+## When to Use Flight Control
+
+Flight Control works best when:
+
+- AI agents are part of your development workflow
+- Work benefits from clear specification before execution
+- You need traceability from outcomes to implementation
+- Multiple people (or AI sessions) contribute to a single outcome
+
+It may be overkill for:
+
+- Quick one-off scripts
+- Solo exploratory coding
+- Highly uncertain R&D with no clear outcomes
+
+## Next Steps
+
+- [Missions](missions.md) — Learn to write outcome-driven mission statements
+- [Flights](flights.md) — Create technical specifications with pre/post checklists
+- [Legs](legs.md) — Structure AI-optimized implementation steps
+- [Workflow](workflow.md) — Understand the end-to-end flow

container/mission-control/docs/workflow.md

@@ -0,0 +1,473 @@
+# Workflow
+
+This document describes how work flows through Flight Control from mission inception to completion.
+
+## The Complete Flow
+
+```mermaid
+flowchart TB
+    subgraph MISSION
+        direction TB
+        planning[planning] --> active[active] --> completed[completed]
+        planning -.-> aborted[aborted]
+
+        subgraph " "
+            direction LR
+            flightA[Flight A] --> legsA[legs]
+            flightB[Flight B] --> legsB[legs]
+            flightC[Flight C] --> legsC[legs]
+        end
+
+        active --> flightA
+        active --> flightB
+        active --> flightC
+        legsA --> completed
+        legsB --> completed
+        legsC --> completed
+    end
+```
+
+## Phase 1: Mission Definition
+
+### Starting Point
+
+Work begins with an outcome someone wants to achieve:
+
+> "We need users to be able to authenticate securely"
+
+This human need becomes a mission.
+
+### Mission Creation
+
+1. **Write the outcome** — What does success look like?
+2. **Define success criteria** — How will we know we're done?
+3. **Identify stakeholders** — Who cares about this outcome?
+4. **Document constraints** — What boundaries exist?
+
+```markdown
+# Mission: Secure User Authentication
+
+## Outcome
+Users can securely access their accounts without credential friction.
+
+## Success Criteria
+- [ ] Users can create accounts
+- [ ] Users can log in and maintain sessions
+- [ ] Password reset flow exists
+- [ ] Security audit passes
+
+## Stakeholders
+- End users, Security team, Support team
+
+## Constraints
+- Must complete before Q2 launch
+- Must meet SOC2 requirements
+```
+
+### Mission State: `planning`
+
+The mission exists but no work has started. This is the time for:
+- Refining the outcome statement
+- Adjusting success criteria
+- Identifying initial flights
+
+## Phase 2: Flight Planning
+
+### Decomposing the Mission
+
+A mission typically requires multiple flights. Identify the major work areas:
+
+```
+Mission: Secure User Authentication
+├── Flight: Account Creation
+├── Flight: Login and Sessions
+├── Flight: Password Reset
+└── Flight: Security Hardening
+```
+
+### Creating the First Flight
+
+Start with the flight that unblocks others or provides the most learning:
+
+```markdown
+# Flight: Account Creation
+
+## Mission Link
+[Secure User Authentication](../mission.md)
+- Contributing to: "Users can create accounts"
+
+## Pre-Flight
+
+### Objective
+Users can register new accounts with email and password.
+
+### Open Questions
+- [ ] What password requirements?
+- [ ] Email verification required before use?
+
+### Design Decisions
+(To be filled as questions are resolved)
+
+### Prerequisites
+- [ ] Database provisioned
+- [ ] API framework set up
+```
+
+### Flight State: `planning`
+
+Pre-flight phase. Resolve open questions, document decisions, verify prerequisites.
+
+## Phase 3: Pre-Flight Completion
+
+### Resolving Questions
+
+Each open question gets answered and documented:
+
+```markdown
+### Open Questions
+- [x] What password requirements?
+- [x] Email verification required before use?
+
+### Design Decisions
+
+**Password Requirements**: Minimum 8 characters, 1 uppercase, 1 number
+- Rationale: Balance security and usability
+- Decided by: Security team
+
+**Email Verification**: Required before accessing protected features
+- Rationale: Prevent spam accounts
+- Decided by: Product requirements
+```
+
+### Defining Legs
+
+With decisions made, break the flight into legs:
+
+```markdown
+### Legs
+- [ ] `create-user-model` - Database model for users
+- [ ] `registration-endpoint` - API endpoint for registration
+- [ ] `email-verification` - Verification email and confirmation flow
+- [ ] `registration-tests` - Test coverage for registration
+```
+
+### Pre-Flight Checklist
+
+Complete the gate check:
+
+```markdown
+### Pre-Flight Checklist
+- [x] All open questions resolved
+- [x] Design decisions documented
+- [x] Prerequisites verified
+- [x] Legs defined with acceptance criteria
+```
+
+### Flight State: `ready`
+
+Pre-flight complete. Ready for execution.
+
+## Phase 4: Leg Execution
+
+### Mission State: `active`
+
+When the first leg begins, the mission becomes active.
+
+### Flight State: `in-flight`
+
+Legs are being executed. A [flight log](flight-logs.md) tracks progress, recording when legs start and complete, decisions made during execution, and any deviations or anomalies encountered.
+
+### Leg Lifecycle
+
+Each leg follows its own progression:
+
+```
+planning ──► ready ──► in-flight ──► landed ──► completed
+```
+
+**Example: `create-user-model` leg**
+
+```markdown
+# Leg: create-user-model
+
+## Objective
+Create the User model with authentication fields.
+
+## Acceptance Criteria
+- [ ] User model in schema
+- [ ] Fields: id, email, password_hash, verified, timestamps
+- [ ] Migration applied
+- [ ] Types generated
+```
+
+**Execution flow:**
+
+1. Leg design approved, moves to `ready`
+2. Developer begins, leg moves to `in-flight`
+3. Developer completes implementation, leg moves to `landed`, flight log updated
+4. Reviewer verifies acceptance criteria met
+5. Leg moves to `completed`
+
+### Parallel vs. Sequential Legs
+
+Some legs can run in parallel:
+
+```
+create-user-model ────► registration-endpoint ────► registration-tests
+                  └──► email-verification ────────┘
+```
+
+The model must exist first, but the endpoint and email flows can be built simultaneously, then tests cover everything.
+
+### Handling Aborted Legs
+
+When a leg can't proceed:
+
+1. Mark it `aborted` — changes are rolled back
+2. Determine if it needs:
+   - Flight-level decision (update the flight)
+   - External resolution (wait for dependency)
+   - New leg with updated requirements
+
+```markdown
+## Status: aborted
+
+**Reason**: Email service credentials not available in dev environment
+**Changes**: Rolled back
+**Next**: New leg after DevOps provisions SendGrid API key
+```
+
+## Phase 5: Flight Completion
+
+### All Legs Complete
+
+When every leg reaches `completed`:
+
+```markdown
+### Legs
+- [x] `create-user-model` - completed
+- [x] `registration-endpoint` - completed
+- [x] `email-verification` - completed
+- [x] `registration-tests` - completed
+```
+
+### Post-Flight Checklist
+
+```markdown
+### Completion Checklist
+- [x] All legs completed
+- [x] Code merged to main
+- [x] Tests passing in CI
+- [x] Documentation updated
+```
+
+### Verification
+
+Confirm the flight achieved its objective:
+
+```markdown
+### Verification
+
+Manual test completed:
+1. ✓ Created account with test@example.com
+2. ✓ Received verification email
+3. ✓ Clicked link, account verified
+4. ✓ Can access protected features
+```
+
+### Flight Debrief
+
+**Run `/flight-debrief` to capture learnings.** This is a required step, not optional.
+
+The debrief skill will:
+- Analyze what went well and what could improve
+- Identify process and technical lessons
+- Recommend methodology improvements
+- Update project documentation if needed
+
+The debrief artifact becomes part of the flight record and informs future flights.
+
+### Flight State: `landed`
+
+Post-flight complete. The flight achieved its objective.
+
+## Phase 6: Mission Progression
+
+### Tracking Mission Progress
+
+As flights land, mission success criteria get checked:
+
+```markdown
+## Success Criteria
+- [x] Users can create accounts ← Flight: Account Creation landed
+- [ ] Users can log in and maintain sessions ← Flight: Login in-flight
+- [ ] Password reset flow exists ← Flight: Password Reset planning
+- [ ] Security audit passes ← Flight: Security Hardening planning
+```
+
+### Spawning New Flights
+
+Discoveries during execution may require new flights:
+
+> "During the Login flight, we discovered we need rate limiting to prevent brute force attacks."
+
+Create a new flight:
+
+```
+Mission: Secure User Authentication
+├── Flight: Account Creation [landed]
+├── Flight: Login and Sessions [in-flight]
+├── Flight: Password Reset [planning]
+├── Flight: Security Hardening [planning]
+└── Flight: Rate Limiting [NEW - planning]
+```
+
+### Mission Completion
+
+When all success criteria are met:
+
+```markdown
+## Success Criteria
+- [x] Users can create accounts
+- [x] Users can log in and maintain sessions
+- [x] Password reset flow exists
+- [x] Security audit passes
+```
+
+### Mission Debrief
+
+**Run `/mission-debrief` to perform a retrospective.** This is a required step, not optional.
+
+The debrief skill will:
+- Assess whether the mission achieved its stated outcomes
+- Synthesize lessons from all flight debriefs
+- Capture process and methodology improvements
+- Interview participants for qualitative insights
+
+The mission debrief is the primary source for improving Flight Control itself.
+
+### Mission State: `completed`
+
+All outcomes achieved. The mission can be archived with its debrief.
+
+## Feedback Loops
+
+### Upward Feedback
+
+Information flows from legs to flights to missions:
+
+- **Leg → Flight**: Completion status, discovered complexity, blockers (captured in flight log)
+- **Flight → Mission**: Progress on success criteria, new flight needs
+
+### Downward Feedback
+
+Guidance flows from missions to flights to legs:
+
+- **Mission → Flight**: Priority changes, constraint updates
+- **Flight → Leg**: Design decisions, context updates, flight log history
+
+### Adaptation
+
+When circumstances change:
+
+1. **Leg-level**: Block the leg, create new leg
+2. **Flight-level**: Divert the flight, re-plan
+3. **Mission-level**: Adjust success criteria or abort
+
+## Handling Diversions
+
+### When to Divert vs. Create New Flight
+
+**Divert the current flight when:**
+- The objective remains the same but the approach must change
+- External factors (security issues, API changes) invalidate the current plan
+- Discovered complexity requires re-planning but the goal is unchanged
+
+**Create a new flight when:**
+- A completely new objective emerges
+- The discovered work is independent of the current flight's goal
+- The new work serves different mission success criteria
+
+### In-Flight Modifications
+
+Flights can be modified while `in-flight` — for example, when planned legs need to change due to discoveries during execution. Update the flight artifact and record the change and rationale in the flight log.
+
+### Flight Abortion
+
+When a flight must be cancelled, changes are rolled back:
+
+```markdown
+## Status: aborted
+
+**Reason**: Security audit revealed JWT vulnerability requires a fundamentally different approach
+**Changes**: Rolled back — new flight will be created for Auth0 integration
+```
+
+### Mission Abortion
+
+Sometimes missions should be cancelled:
+
+```markdown
+## Status: aborted
+
+**Reason**: Business pivot - authentication now handled by parent company SSO
+**Learning**: Coordinate with enterprise architecture earlier
+**Artifacts**: Account creation flight code preserved in branch for reference
+```
+
+Document the reason for future reference.
+
+## State Summary
+
+### All States in One View
+
+```
+MISSION STATES
+planning ──► active ──► completed
+                │
+                └──► aborted
+
+FLIGHT STATES
+planning ──► ready ──► in-flight ──► landed ──► completed
+                           │
+                           └──► aborted
+
+LEG STATES
+planning ──► ready ──► in-flight ──► landed ──► completed
+                           │
+                           └──► aborted
+```
+
+## When to Create vs. Modify
+
+### Create New
+
+- **Mission**: New outcome needed
+- **Flight**: New area of work identified
+- **Leg**: Requirements changed after `in-flight`
+
+### Modify Existing
+
+- **Mission**: Refining success criteria during `planning`
+- **Flight**: Updating during `planning` phase
+- **Leg**: Only while `planning` (before work begins)
+
+### Rule of Thumb
+
+Once work begins, create new rather than modify. This preserves history and prevents confusion about what was actually requested.
+
+## Quick Reference
+
+| Phase | Mission State | Flight State | Leg State | Action |
+|-------|---------------|--------------|-----------|--------|
+| Defining outcomes | planning | — | — | — |
+| Planning first flight | planning | planning | — | — |
+| Pre-flight complete | planning | ready | — | — |
+| Designing first leg | active | in-flight | planning | — |
+| Leg design approved | active | in-flight | ready | — |
+| Executing leg | active | in-flight | in-flight | — |
+| Leg implementation done | active | in-flight | landed | — |
+| Leg reviewed | active | in-flight | completed | — |
+| Flight done | active | landed | — | — |
+| Flight debriefed | active | completed | — | `/flight-debrief` |
+| All flights done | completed | — | — | `/mission-debrief` |