---
name: adaptive-constraints
description: >-
  Dynamically adjust constraint loading based on
  task complexity. Simple tasks get minimal
  governance; complex tasks get full enforcement.
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
estimated_tokens: 180
---

# Adaptive Constraints (Nen-Free Zones)

## Problem

All missions load the same governance weight
regardless of complexity. Past 150 soft rules,
compliance drops for all rules. A focused 50-line
CLAUDE.md beats an unfocused 300-line one; bad
context performs worse than none. SWE-agent mini
proves 100 lines of focused code reaches 74% on
SWE-bench Verified. Simple tasks need less
governance, not the same governance.

## Constraint Profiles

| Profile | Task Type | Constraints Loaded | Governance |
|---------|-----------|-------------------|------------|
| Minimal | quickfix, single-file changes | Core safety only (no `--no-verify`, no secrets) | No war-room, no scope-guard, no plan review |
| Standard | tactical missions, multi-file | Core safety, scope-guard, and proof-of-work | Plan review, single checkpoint |
| Full | full/standard missions, architecture changes | All constraints, war-room, and extended thinking | Full checkpoints, iteration governor |

## Profile Selection

### By Mission Type

| Mission Type | Default Profile |
|-------------|----------------|
| `quickfix` | Minimal |
| `tactical` | Standard |
| `standard` | Full |
| `full` | Full |

### Manual Override

Override with `--constraints=minimal|standard|full`.
The override bypasses mission-type defaults and
risk upgrades (always wins).

### User Directive Override (Natural Language)

Parse the command-args and any free-text the user
provides at mission start. If a recognized trust
signal is present, treat it as a manual override
with the tier shown below. Directive overrides
behave exactly like `--constraints=` flags: they win
over mission-type defaults and risk upgrades, but
never bypass the Safety Floor.

| User phrase contains | Effective profile | Notes |
|----------------------|-------------------|-------|
| "ignore scope guard" / "skip scope guard" | Standard with scope-guard stripped | Acts like Minimal for scope, keeps proof-of-work |
| "ultrathink" / "deep dive" / "be thorough" | Full quality, Minimal checkpoints | Use full reasoning depth, skip blocking gates |
| "don't ask" / "stop asking" / "no more questions" | Minimal | Auto-continue all phase transitions |
| "be autonomous" / "trust your judgment" | Minimal | Same as above |
| "I trust you" / "go ahead" / "just do it" | Minimal | Same as above |
| "ask before each step" / "supervised" | Full | Force maximum oversight |
| "explain everything" / "teach me" | Full and verbose | Pair with explanatory output style |

Match is case-insensitive substring. Multiple
matches: the most-restrictive directive wins (Full
beats Minimal). The orchestrator records the
matched directive and resulting profile in
`.attune/mission-state.json` under
`directive_override`:

```json
{
  "directive_override": {
    "matched_phrase": "ignore scope guard",
    "effective_profile": "standard_minus_scope_guard",
    "matched_at": "2026-04-25T17:30:00Z"
  }
}
```

When a directive override is detected, the
orchestrator MUST acknowledge it once at mission
start, then stop asking for the corresponding
checkpoints. Repeated approval-seeking after a
directive override is itself a workflow bug; see
`/sanctum:fix-workflow` retrospectives for examples.

#### What Directives Cannot Override

The Safety Floor below applies regardless of
directive. Even "trust me, just do it" cannot waive:

- Pre-commit hooks
- Proof-of-work evidence capture
- Destructive-operation confirmation (rm -rf, force
  push, DROP TABLE, branch deletion)
- External-facing actions (PR creation, issue
  comments, release tags)
- Cost threshold breaches (token/time budget exceeded)

When the orchestrator hits one of these even under
a Minimal directive override, it pauses. The
override gives autonomy on routine decisions; it
does not surrender oversight on irreversible ones.

#### Persistent vs Per-Mission Directives

Directive overrides apply for the current mission
only. They do not persist to subsequent missions.
For permanent autonomy escalation, the user should
either set the profile flag on each mission or
elevate skill trust tiers via repeated successful
runs (see `trust-tier.md`).

### Risk Upgrade

`leyline:risk-classification` can upgrade (never
downgrade) the profile:

| Risk Level | Effect |
|------------|--------|
| GREEN/YELLOW | Use mission-type default |
| ORANGE | Upgrade to Standard minimum |
| RED | Upgrade to Full |

Selection order: mission-type default, then risk
upgrade, then manual override.

## What Each Profile Strips

### Minimal (vs Full)

Stripped:

- scope-guard worthiness evaluation
- war-room checkpoint
- plan-review iteration loop
- backlog triage (issue creation from Out of Scope)
- additive-bias-defense check

Kept:

- proof-of-work evidence (always required)
- Iron Law enforcement (always active)
- Pre-commit hooks (always run)
- Destructive operation confirmation (always prompt)

### Standard (vs Full)

Stripped:

- war-room checkpoint
- additive-bias-defense audit
- Plan review limited to single pass (no iteration
  governor, no multi-round revision)

Kept:

- scope-guard worthiness evaluation
- proof-of-work evidence
- Single checkpoint per critical phase
- Pre-commit hooks
- Iron Law enforcement
- Destructive operation confirmation

## Safety Floor

These constraints are never stripped regardless of
profile, forming the absolute minimum governance:

1. **Pre-commit hooks** always run. No path through
   adaptive-constraints disables `--no-verify`
   protection.
2. **proof-of-work evidence** is always required.
   Every mission must produce verifiable artifacts.
3. **Hard vows from vow-enforcement** are always
   enforced. Soft vows may be relaxed by profile.
4. **Destructive operation confirmation** always
   prompts. No silent `rm -rf`, `git push --force`,
   or `DROP TABLE`.

Any code path bypassing the safety floor is a bug.
The floor is not configurable.

## Token Savings

| Profile | Modules Skipped | Tokens Saved |
|---------|----------------|--------------|
| Minimal | 4 (scope-guard, war-room, plan-review, additive-bias-defense) | ~2000 per mission |
| Standard | 2 (war-room, additive-bias-defense) | ~800 per mission |
| Full | 0 (baseline) | 0 |

Savings compound: 5 quickfixes save ~10k tokens.

## Integration with Phase Routing

The `phase-routing.md` module consults adaptive-
constraints before each phase transition:

1. At mission start, the orchestrator determines the
   constraint profile and records it in
   `.attune/mission-state.json` under
   `constraint_profile`.

2. Before each phase, phase-routing checks the
   active profile against the phase's governance
   requirements.

3. If the profile says "skip checkpoint for this
   phase," phase-routing auto-continues without
   presenting the checkpoint prompt.

4. The profile is locked at mission start. No mid-
   mission changes. If risk escalates, the
   orchestrator logs a warning; the user can abort
   and restart with a higher profile.

### Phase-Routing Decision Table

| Phase Transition | Minimal | Standard | Full |
|-----------------|---------|----------|------|
| brainstorm to specify | auto-continue | auto-continue | checkpoint |
| specify to plan | auto-continue | checkpoint | checkpoint and backlog triage |
| plan to execute | auto-continue | single-pass review | full review loop and war-room |
| post-execute | proof-of-work only | proof-of-work, scope check | proof-of-work, scope, and bias audit |

---
name: context-injector
description: >-
  Build structured revision prompts from feedback
  files so the planning skill addresses specific
  complaints in the next iteration.
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
estimated_tokens: 150
---

# Context Injector

## Purpose

When a plan revision is requested, transform the
structured feedback into a prompt addition that guides
the planning skill to address the specific complaints
without repeating rejected patterns.

## Revision Prompt Template

The context injector reads the latest
`round-N.json` and builds this prompt block:

```
## Revision Context (Round {N} Feedback)

The previous plan version was reviewed. Address
these items in the revised plan:

### Sections Requiring Revision

**{section_name}** (verdict: {verdict})
Feedback: {rationale}
{annotations if any}

### Sections Approved (Do Not Change)

- {section_name}: approved, keep as-is

### Anti-Patterns to Avoid

Do NOT repeat these patterns from the rejected plan:
- {extracted patterns from rejected sections}

### Constraints Added by Reviewer

- {constraint annotations}
```

## Building the Prompt

### Algorithm

1. Read `.attune/plan-history/feedback/round-N.json`
2. For each section with verdict `revise` or `reject`:
   - Include the section name, verdict, and rationale
   - Include any typed annotations
   - Extract specific patterns to avoid from rejected
     content
3. For each section with verdict `approve`:
   - List as "keep as-is" to prevent regression
4. Collect all `constraint` type annotations into a
   dedicated section
5. If bias findings exist, include them as additional
   constraints

### Feeding Back to the Planning Skill

The revision prompt is passed as additional context
when re-invoking `Skill(attune:project-planning)`:

```
The orchestrator re-invokes the planning skill with:
1. The original specification (docs/specification.md)
2. The revision context block (built above)
3. The previous plan version for reference
```

The planning skill sees the revision context as
requirements that constrain its output.

## War Room Feedback

When the war room returns concerns or rejection:

1. Read the war-room verdict from mission state
2. Convert war-room concerns into the same revision
   prompt format
3. Include the prosecution counsel's specific
   objections as constraints
4. Mark this as "war-room feedback" so the planning
   skill knows the source

## Guard Rails

- The context injector NEVER modifies the plan directly
- It only produces prompt context for the planning skill
- Approved sections are explicitly marked "do not change"
  to prevent regression during revision

---
name: feedback-collector
description: >-
  Capture section-level verdicts (approve/revise/reject)
  with optional rationale and typed annotations, write
  structured feedback to .attune/plan-history/feedback/.
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
estimated_tokens: 200
---

# Feedback Collector

## Purpose

Capture the user's section-by-section review verdicts
and write them as structured JSON for consumption by
the context injector and plan versioner.

## Verdict Types

| Verdict | Meaning | Requires Rationale |
|---------|---------|-------------------|
| `approve` | Section is acceptable | No |
| `revise` | Section needs changes | Yes |
| `reject` | Section is wrong approach | Yes |

## Optional Typed Annotations

When the user wants finer-grained control than
section-level verdicts, they can add typed annotations:

| Type | Purpose |
|------|---------|
| `reject` | Remove this entirely |
| `revise` | Change this, here is why |
| `question` | I do not understand this |
| `constraint` | Add this requirement |

## Feedback File Schema

Written to `.attune/plan-history/feedback/round-N.json`:

```json
{
  "round": 1,
  "plan_version": 1,
  "timestamp": "2026-04-13T14:30:00Z",
  "sections": [
    {
      "name": "architecture",
      "verdict": "revise",
      "rationale": "Split the API layer into read/write services",
      "annotations": []
    },
    {
      "name": "phase-1",
      "verdict": "approve",
      "rationale": null,
      "annotations": []
    },
    {
      "name": "phase-2",
      "verdict": "reject",
      "rationale": "Wrong approach entirely, use event sourcing",
      "annotations": [
        {
          "type": "constraint",
          "text": "Must support event replay for auditing"
        }
      ]
    }
  ],
  "overall": "revision_requested",
  "bias_findings": [],
  "war_room": null
}
```

## Field Descriptions

| Field | Type | Description |
|-------|------|-------------|
| `round` | int | Review round number (1-3) |
| `plan_version` | int | Version of plan being reviewed |
| `timestamp` | ISO 8601 | When feedback was collected |
| `sections` | array | Per-section verdicts |
| `sections[].name` | string | Section identifier |
| `sections[].verdict` | string | approve/revise/reject |
| `sections[].rationale` | string or null | Why, if not approved |
| `sections[].annotations` | array | Optional typed annotations |
| `overall` | string | `approved` or `revision_requested` |
| `bias_findings` | array | From additive-bias-defense scan |
| `war_room` | object or null | War-room verdict (filled after deliberation) |

## Overall Verdict Logic

```
if len(sections) > 0 and all sections have verdict "approve":
    overall = "approved"
elif len(sections) == 0:
    overall = "error: no sections parsed"
else:
    overall = "revision_requested"
```

An empty sections array MUST NOT resolve to "approved."
If the plan parser produces zero sections, report the
error rather than silently approving an unreviewed plan.

## Writing the Feedback File

```bash
mkdir -p .attune/plan-history/feedback
# Write JSON to round-N.json
```

The orchestrator writes the JSON after collecting all
section verdicts in a single review pass.

---
name: iteration-governor
description: >-
  Track review rounds (max 3), warn at round 2,
  force decision at round 3 exhaustion with
  escalation options.
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
estimated_tokens: 150
---

# Iteration Governor

## Purpose

Prevent infinite plan-churn by capping review
iterations at 3 rounds. If the plan is still not
satisfactory after 3 rounds, the problem is likely
upstream in the specification.

## Round Tracking

| Round | Status | User Sees |
|-------|--------|-----------|
| 1 | Normal | "Round 1/3" in review header |
| 2 | Warning | "Round 2/3 — next round is final" |
| 3 | Final | "Final round (3/3)" |
| After 3 | Blocked | Escalation options presented |

## War Room Feedback Counts

War-room feedback that triggers a revision counts
toward the iteration cap. If the user approves on
round 2 but the war room sends it back, that revision
is round 3 (final).

Example:
- Round 1: User reviews, requests revision
- Round 2: User approves, war room rejects
- Round 3: Final revision, then forced decision

## Escalation at Cap

When round 3 is exhausted (user or war room still not
satisfied), present these options:

```
Round 3 exhausted. 3 review rounds completed.

Options:
  [A] Approve current version as-is
  [B] Abort mission
  [C] Restart planning from specification
      (re-invoke Skill(attune:project-planning)
       with clean slate, no revision context)
```

Option C resets the iteration counter to 0 and starts
fresh. The previous plan history is preserved for
reference but not fed as context.

## Round 2 Warning

At the start of round 2 review, display:

```
--- Warning: Round 2 of 3 ---
This is the penultimate review round.
Round 3 will be the final opportunity to revise.
After round 3, you must approve, abort, or restart.
-----------------------------------------
```

## State Integration

The governor reads and writes `plan_review.current_round`
in `.attune/mission-state.json`. See mission-state
module for the schema.

## Governor Logic

```
function check_iteration(current_round):
    # Called BEFORE round starts. current_round is
    # incremented after each completed round, so
    # current_round == 4 means 3 rounds completed.
    if current_round > 3:
        present_escalation_options()
        return BLOCKED
    elif current_round == 3:
        display "Final round (3/3)"
        return FINAL
    elif current_round == 2:
        display round 2 warning
        return WARNING
    else:
        return NORMAL
```

---
name: mission-state
description: Mission state schema, persistence to .attune/mission-state.json, and recovery protocol
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
estimated_tokens: 200
---

# Mission State

## State Schema

```json
{
  "mission_id": "mission-20260207-220000",
  "type": "tactical",
  "started_at": "2026-02-07T22:00:00Z",
  "updated_at": "2026-02-07T23:30:00Z",
  "status": "in_progress",
  "phases": {
    "brainstorm": {
      "status": "skipped",
      "reason": "Not in mission type 'tactical'"
    },
    "specify": {
      "status": "skipped",
      "reason": "Not in mission type 'tactical'"
    },
    "plan": {
      "status": "completed",
      "started_at": "2026-02-07T22:00:00Z",
      "completed_at": "2026-02-07T22:45:00Z",
      "artifact": "docs/implementation-plan.md",
      "notes": "Generated 24 tasks across 5 phases"
    },
    "execute": {
      "status": "in_progress",
      "started_at": "2026-02-07T22:50:00Z",
      "completed_at": null,
      "artifact": ".attune/execution-state.json",
      "notes": "12/24 tasks complete"
    }
  },
  "risk_summary": {
    "GREEN": 18,
    "YELLOW": 4,
    "RED": 2,
    "CRITICAL": 0
  },
  "errors": [
    {
      "phase": "execute",
      "task_id": "T015",
      "error": "Test timeout on integration suite",
      "category": "TRANSIENT",
      "recovery": "Retried successfully",
      "resolved": true
    }
  ],
  "user_decisions": [
    {
      "checkpoint": "plan → execute",
      "decision": "continue",
      "timestamp": "2026-02-07T22:48:00Z"
    }
  ],
  "plan_review": {
    "current_round": 2,
    "max_rounds": 3,
    "status": "in_review",
    "versions": [
      {
        "version": 1,
        "created_at": "2026-04-13T14:00:00Z",
        "path": ".attune/plan-history/plan-v1.md",
        "feedback_path": ".attune/plan-history/feedback/round-1.json",
        "overall_verdict": "revision_requested"
      },
      {
        "version": 2,
        "created_at": "2026-04-13T14:30:00Z",
        "path": ".attune/plan-history/plan-v2.md",
        "feedback_path": null,
        "overall_verdict": null
      }
    ],
    "war_room_verdict": null,
    "bias_findings_count": 3
  }
}
```

## Field Descriptions

| Field | Type | Description |
|-------|------|-------------|
| `mission_id` | string | Unique ID: `mission-{YYYYMMDD}-{HHMMSS}` |
| `type` | string | Mission type: `full`, `standard`, `tactical`, `quickfix` |
| `started_at` | ISO 8601 | Mission start timestamp |
| `updated_at` | ISO 8601 | Last state update timestamp |
| `status` | string | `in_progress`, `completed`, `paused`, `aborted`, `failed` |
| `phases` | object | Per-phase status, timestamps, artifacts |
| `risk_summary` | object | Count of tasks per risk tier |
| `errors` | array | Errors encountered during execution |
| `user_decisions` | array | User checkpoint decisions |
| `plan_review` | object | Interactive review loop state |
| `plan_review.current_round` | int | Current review round (1-3) |
| `plan_review.max_rounds` | int | Maximum rounds (default 3) |
| `plan_review.status` | string | `in_review`, `approved`, `war_room_pending` |
| `plan_review.versions` | array | Per-version metadata |
| `plan_review.war_room_verdict` | string or null | `approved`, `concerns`, `rejected` |
| `plan_review.bias_findings_count` | int | Number of additive bias findings |

## Persistence

State is persisted to `.attune/mission-state.json`:

- **Write frequency**: After each phase completion and on error
- **Atomic write**: Uses temp file + rename pattern to prevent corruption
- **Directory creation**: Creates `.attune/` if it doesn't exist

```bash
# State file location
.attune/mission-state.json
```

## Recovery Protocol

When resuming a mission (`/attune:mission --resume`):

### Step 1: Load State

```
Read .attune/mission-state.json
If not found: No mission to resume, start fresh
If found: Parse and validate
```

### Step 2: Validate Artifacts

For each completed phase, verify its artifact still exists on disk:

```
For each phase where status == "completed":
    Check artifact path exists
    If missing: Mark phase as "needs_rerun"
    If present: Confirm still valid (quality checks)
```

### Step 3: Continue from Last Completed Phase

```
Find first phase where status != "completed" and status != "skipped"
If "in_progress": Resume this phase
If "pending": Start this phase
If all complete: Mission already done
```

### Step 4: Display Resume Summary

```
Resuming Mission: mission-20260207-220000
  Type: tactical
  Status: in_progress

  Phase Status:
    plan:    completed (22:00 - 22:45)
    execute: in_progress (12/24 tasks, started 22:50)

  Continuing from: execute phase
  Next task: T013
```

## State Transitions

```
           start
             |
             v
        in_progress ──────► completed
             |
             ├──► paused (--resume to continue)
             |
             ├──► aborted (user choice)
             |
             └──► failed (unrecoverable error)
```

- `paused → in_progress`: Via `--resume`
- `failed → in_progress`: Via `--resume --force` (resets failed phase)
- `aborted`: Terminal state (start new mission to retry)

### Plan Review Status Transitions

```
plan_review.status:
    pending --> in_review (first section presented)
    in_review --> approved (all sections approved)
    in_review --> revision_requested (any section rejected/revised)
    approved --> war_room_pending (war room invoked)
    war_room_pending --> approved (war room approves)
    war_room_pending --> revision_requested (war room rejects)
    revision_requested --> in_review (next round starts)
```

---
name: mission-types
description: Mission type definitions, phase sequences, auto-detection logic, and custom type support
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
estimated_tokens: 200
---

# Mission Types

## Type Definitions

### full

**Phases**: brainstorm → specify → plan → execute

**Use when**: Starting from scratch with no existing artifacts. The complete development lifecycle from ideation to implementation.

**Auto-detected when**: None of the following exist:
- `docs/project-brief.md`
- `docs/specification.md`
- `docs/implementation-plan.md`

### standard

**Phases**: specify → plan → execute

**Use when**: A project brief exists but needs to be turned into a specification, planned, and executed.

**Auto-detected when**: `docs/project-brief.md` exists but `docs/specification.md` does not.

### tactical

**Phases**: plan → execute

**Use when**: Specification is complete and ready for planning and implementation.

**Auto-detected when**: `docs/specification.md` exists but `docs/implementation-plan.md` does not.

### quickfix

**Phases**: execute

**Use when**: Implementation plan exists and is ready for execution. Useful for resuming execution or running a quick fix with a pre-written plan.

**Auto-detected when**: `docs/implementation-plan.md` exists.

### review

**Phases**: scope → investigate → verify → report

**Use when**: The work is observational rather than constructive.
Dogfooding the ecosystem, auditing a subsystem, or reviewing an
existing feature. The deliverable is findings with evidence, not
implemented code.

**Auto-detected when**: The request names existing software to review,
audit, or dogfood rather than a new artifact to build. This is the one
type selected from request intent instead of from artifacts, so its
check runs before the artifact ladder below.

**Output**: `reports/<topic>-<YYYY-MM-DD>.md`, a findings-and-recommendations
report with evidence references. No build artifact is required as input
and none is produced.

**War-room gate**: does not apply. The mandatory war-room approval in
`plan-review.md` guards the plan-to-execute transition, and a review
mission never plans or executes. Gating it there would strand the
mission at a checkpoint with no matching phase. Directive overrides
("ignore scope guard", "ultrathink") apply as they do elsewhere.

**Reuses**: `imbue:feature-review` for scoring, the `pensive:*` review
skills for domain lenses, and `imbue:proof-of-work` for the evidence
bar. The orchestrator adds sequencing, not new review logic.

## Auto-Detection Logic

```
function detect_mission_type(request):
    # Intent first. A tree full of build artifacts looks identical
    # whether the ask is "ship this" or "audit this", so artifact
    # detection cannot distinguish them. Issue: discussion #586.
    if request_is_observational(request):
        return "review"
    elif exists("docs/implementation-plan.md"):
        return "quickfix"
    elif exists("docs/specification.md"):
        return "tactical"
    elif exists("docs/project-brief.md"):
        return "standard"
    else:
        return "full"
```

`request_is_observational` matches asks to review, audit, dogfood,
assess, or evaluate existing software, as opposed to asks to build,
add, implement, or fix. When the wording is genuinely ambiguous, the
orchestrator surfaces both candidates rather than guessing.

**Priority**: Among the build types, later artifacts take precedence. If both a brief and a spec exist, the type is `tactical` (because the spec is a more advanced artifact).

**Quality check**: Existence alone is not sufficient. The artifact must be non-empty and contain expected sections. See `state-detection.md` for validation rules.

## User Override

Users can override auto-detection:

```bash
# Force full lifecycle even if artifacts exist
/attune:mission --type full

# Skip brainstorming, go straight to spec
/attune:mission --type standard

# Just plan and execute
/attune:mission --type tactical

# Execute existing plan
/attune:mission --type quickfix

# Audit or dogfood without building anything
/attune:mission --type review
```

## Custom Phase Sequences

For non-standard workflows, users can specify exact phases:

```bash
# Brainstorm then execute (skip spec and plan)
/attune:mission --phases brainstorm,execute

# Specify and plan without execution
/attune:mission --phases specify,plan
```

**Validation**: Custom sequences must maintain phase order (brainstorm < specify < plan < execute). Out-of-order phases are rejected. Review phases (scope < investigate < verify < report) form their own ordered set and cannot be interleaved with build phases: a mission either builds or reviews.

## Type Selection Display

When the orchestrator starts, it displays the detected type and asks for confirmation:

```
Mission Type: tactical (auto-detected)
  Reason: docs/specification.md exists, no implementation plan found
  Phases: plan → execute

Proceed with this mission type? [Y/n/override]
```

With `--auto` flag, this confirmation is skipped.

---
name: phase-routing
description: Phase execution protocol, transition hooks, user checkpoints, and error handling via damage-control
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
estimated_tokens: 250
---

# Phase Routing

## Phase Execution Protocol

For each phase in the mission type's sequence, the orchestrator follows this protocol:

```
Phase: {phase_name}
  |
  1. Pre-Phase Validation
  |   Check prerequisites (prior phase artifacts exist and are valid)
  |   If invalid: STOP, report missing prerequisites
  |
  2. Invoke Skill
  |   Call Skill(attune:{phase-skill})
  |   The skill handles its own workflow entirely
  |
  3. Post-Phase Artifact Check
  |   Verify the expected output artifact was created
  |   If missing: Phase failed, enter error handling
  |
  4. Update Mission State
  |   Record phase completion in .attune/mission-state.json
  |   Include timestamps, artifact paths, any warnings
  |
  5. User Checkpoint (skippable with --auto)
  |   Present phase results and ask to proceed
  |   User can: continue, pause, abort, or re-run phase
  |
  6. Error Handling
      If phase failed: invoke leyline:damage-control
      Determine recovery action (retry, skip, escalate)
```

## Skill Invocation Table

| Phase | Skill Call | Expected Output |
|-------|-----------|-----------------|
| brainstorm | `Skill(attune:project-brainstorming)` | `docs/project-brief.md` |
| specify | `Skill(attune:project-specification)` | `docs/specification.md` |
| plan | `Skill(attune:project-planning)` | `docs/implementation-plan.md` |
| execute | `Skill(attune:project-execution)` | Code changes and `.attune/execution-state.json` |

## Pre-Phase Validation

Each phase has prerequisites that must be satisfied:

| Phase | Prerequisites |
|-------|--------------|
| brainstorm | None (starting point) |
| specify | `docs/project-brief.md` exists and is valid |
| plan | `docs/specification.md` exists and is valid |
| execute | `docs/implementation-plan.md` exists and is valid |

If a prerequisite is missing but a prior phase should have produced it, the orchestrator reports the gap rather than silently skipping.

## Transition Hooks

Between phases, the orchestrator performs lightweight transitions:

### brainstorm → specify

- Verify project brief is concrete (has goals and constraints)
- Pass brief path to specification skill
- **Backlog triage**: Scan spec/brief for "Out of Scope"
  section. Create a GitHub issue for each deferred item.
  See below.

### specify → plan

- Verify specification has testable requirements
- Check if war-room review was completed (recommended for RED+ projects)
- **Backlog triage**: If the specification skill did not
  already create issues (check for issue numbers in the
  Out of Scope section), create them now.

### plan → execute (Interactive Review Loop)

This transition is no longer a simple checkpoint.
It invokes the full interactive review loop from
`modules/plan-review.md`.

**Transition protocol:**

1. **Version the plan**: invoke plan-versioner to copy
   `docs/implementation-plan.md` to
   `.attune/plan-history/plan-v1.md`

2. **Check iteration governor**: verify round count
   (should be 1 for first pass)

3. **Scan for additive bias**: apply
   `leyline:additive-bias-defense` scrutiny questions
   to each plan section

4. **Present for review**: invoke plan-review to show
   sections one at a time with verdicts

5. **Collect feedback**: if any section is
   revise/reject, invoke feedback-collector

6. **Inject context and re-plan**: if revision needed,
   invoke context-injector, then re-invoke
   `Skill(attune:project-planning)` with revision
   context. Increment round. Go to step 1.

7. **Mandatory war-room gate**: when all sections
   approved, invoke `Skill(attune:war-room)` with
   full context including bias findings and the
   Prosecution Counsel role active

8. **War room verdict**:
   - APPROVE: classify tasks by risk tier, generate
     risk summary, proceed to execute
   - CONCERNS/REJECT: convert war-room feedback to
     revision context, increment round, go to step 1
     (the governor check at step 2 enforces the cap)
   - If iteration governor returns BLOCKED: present
     escalation options (approve as-is / abort /
     restart from spec)

9. **Risk classification**: after war-room approval,
   invoke `leyline:risk-classification` on all tasks
   and generate risk summary for mission state

**This replaces the previous 3-line transition.**
The old behavior (verify, classify, and summarize) is
now step 9 after the review loop completes.

## Post-Phase Backlog Triage

After the **brainstorm** and **specify** phases, scan
the produced artifact for an "Out of Scope" section and
create GitHub issues for each deferred item.

**When to run**: After brainstorm and specify phases.
Skip after plan and execute (no new scope decisions).

**Algorithm**:
1. Read the phase artifact (brief or spec)
2. Find the "Out of Scope" heading
3. Extract each bullet point as a deferred item
4. For each item, check if it already has an issue
   reference (e.g., `(#123)`)
5. For items without references, create a GitHub issue:
   ```bash
   gh issue create \
     --title "[Backlog] <project>: <item summary>" \
     --body "## Context
   Identified during <phase> phase.
   Artifact: <artifact-path>

   ## Description
   <full item text from spec>" \
     --label "feature,low-priority"
   ```
6. Update the artifact's Out of Scope section with
   issue references: `- Item description (#NNN)`
7. Report created issues at the user checkpoint

**Skip conditions**:
- `--no-auto-issues` flag
- Item already has an issue reference
- Fewer than 1 item in Out of Scope section

## User Checkpoints

After each phase, the orchestrator presents a checkpoint:

```
Phase Complete: specify
  Output: docs/specification.md (2,450 words, 8 user stories)
  Duration: 15 minutes
  Status: Success

  Next phase: plan
  [C]ontinue | [P]ause | [A]bort | [R]e-run phase
```

### Checkpoint Behavior

| Choice | Action |
|--------|--------|
| Continue | Proceed to next phase |
| Pause | Save state, exit (resume with `--resume`) |
| Abort | Save state, mark mission as aborted |
| Re-run | Delete phase output, re-invoke the skill |

### Auto Mode

With `--auto` flag, checkpoints are skipped and phases proceed automatically. The orchestrator logs checkpoint data but does not pause.

### Plan Review Checkpoint (replaces standard checkpoint for plan → execute)

The plan-to-execute transition uses the interactive
review loop instead of the standard checkpoint. The
user checkpoint is embedded in the section-by-section
review process (see `modules/plan-review.md`).

The standard checkpoint format (Continue/Pause/Abort/
Re-run) is NOT shown for plan → execute. It is still
used for all other phase transitions.

## Error Handling

When a phase fails (skill errors, artifact not produced, validation failure):

1. **Classify error**: Map to `leyline:damage-control` categories
   - Timeout/context overflow → `context-overflow` module
   - Skill crash → `agent-crash-recovery` module
   - Partial output → `partial-failure-handling` module

2. **Attempt recovery**:
   - TRANSIENT: Retry phase (max 2 attempts)
   - PERMANENT: Present error to user with options
   - CRASH: Clear context, retry with fresh state

3. **Update mission state**: Record error, recovery attempt, and outcome

4. **User decision**: If recovery fails, present options:
   - Retry phase manually
   - Skip phase and continue (if safe)
   - Abort mission

---
name: plan-review
description: >-
  Interactive section-by-section plan review in the
  terminal. Presents architecture first, then phases.
  Collects verdicts, tracks versions, injects feedback,
  governs iterations, and gates on war-room approval.
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
dependencies:
- modules/plan-versioner.md
- modules/feedback-collector.md
- modules/context-injector.md
- modules/iteration-governor.md
- modules/mission-state.md
- leyline:additive-bias-defense
estimated_tokens: 400
---

# Plan Review

## Purpose

Replace the lightweight plan-to-execute checkpoint with
an interactive review loop. The user reviews the plan
section by section, provides verdicts, and the plan is
revised until approved or the iteration cap is reached.
After user approval, the plan must pass a mandatory
war-room review.

## Review Flow

```
plan skill produces docs/implementation-plan.md
         |
         v
Plan Versioner: copy to plan-v1.md
         |
         v
Iteration Governor: check round (1/3)
         |
         v
Additive Bias Scan: scan plan for unjustified additions
  (findings displayed alongside plan sections)
         |
         v
Plan Presenter: show architecture section
  user: approve / revise / reject
         |
Plan Presenter: show phase 1
  user: approve / revise / reject
         |
... (remaining phases) ...
         |
         v
Feedback Collector: write round-N.json
         |
         v
All sections approved?
  |                    |
  no                   yes
  |                    |
  v                    v
Context Injector    Mandatory War Room Gate
  build revision      Skill(attune:war-room)
  re-invoke planning    |
  increment round       v
  loop back           War Room approves?
                        |            |
                        yes          no
                        |            |
                        v            v
                      EXECUTE     Feedback from war room
                                  counts as next round
                                  loop back to review
```

## Section Parsing

Parse `docs/implementation-plan.md` into reviewable
sections:

1. **Architecture section**: everything from the start
   of the plan through the first `## Phase` or
   `## Task` heading. This includes the Goal,
   Architecture, Tech Stack, and File Structure.

2. **Phase sections**: each `## Phase N:` heading and
   its content through the next phase heading or EOF.

If the plan uses `### Task N:` without phase groupings,
group tasks into logical clusters of 3-5 tasks each.

## Presentation Format

### Section Display

```
--- Plan Review: {Section Name} (v{V}, round {R}/{MAX}) ---

{section content, verbatim from the plan}

{bias findings for this section, if any:}
  [BIAS] New caching layer -- which spec requirement
         demands this? (scrutiny Q4: no evidence)

------------------------------------------------------------
Verdict? [A]pprove / [R]evise / re[J]ect
>
```

### Revision Rationale Prompt

When verdict is `revise` or `reject`:

```
Rationale (what to change):
>
```

### Diff Summary (Round 2+)

At the start of round 2+, before section review:

```
--- Changes in v{V} (from round {R-1} feedback) ---
 {section}: +N lines, -M lines
   Addressed: "{feedback summary}"
 {section}: unchanged
-------------------------------------------------
```

## War Room Gate

After all sections are approved:

1. Save the approved plan as the final version
2. Invoke `Skill(attune:war-room)` with:
   - `docs/implementation-plan.md` (approved version)
   - `docs/specification.md` (cross-reference)
   - `.attune/plan-history/feedback/` (revision history)
   - `.attune/plan-history/plan-v*.md` (all versions)
   - Risk classification from `leyline:risk-classification`
   - Additive bias scan findings
3. The Prosecution Counsel role is always active
4. War room verdict determines next step:
   - APPROVE: proceed to execute phase
   - CONCERNS/REJECT: feedback enters revision loop,
     counts toward iteration cap

## Additive Bias Integration

Before presenting each section to the user, scan it
using `leyline:additive-bias-defense`:

1. Apply the 5 scrutiny questions to each proposed
   component or abstraction in the section
2. Flag items where evidence (Q4) or consequence (Q5)
   answers are weak
3. Display findings inline with the section content
4. Record findings in the feedback file

This means the user sees bias warnings before making
their verdict, giving them ammunition for targeted
revision requests.

## State Management

The plan-review module reads and writes the
`plan_review` object in `.attune/mission-state.json`.
See mission-state module for the full schema.

On each round:
- Increment `current_round`
- Append to `versions` array
- Update `status` (in_review / approved / rejected)
- Record `war_room_verdict` when available

---
name: plan-versioner
description: >-
  Copy plan iterations to .attune/plan-history/,
  generate line-level diff summaries between versions,
  and record version metadata in mission state.
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
estimated_tokens: 200
---

# Plan Versioner

## Purpose

Track every iteration of the implementation plan as a
separate file. Generate human-readable diff summaries
showing what changed between versions and why.

## Storage Layout

```
.attune/
  plan-history/
    plan-v1.md          # First version
    plan-v2.md          # After round 1 feedback
    plan-v3.md          # After round 2 feedback
    feedback/
      round-1.json      # Feedback that prompted v2
      round-2.json      # Feedback that prompted v3
```

## Versioning Protocol

### On Initial Plan Creation

When `Skill(attune:project-planning)` produces
`docs/implementation-plan.md`:

1. Create `.attune/plan-history/` if it does not exist
2. Copy `docs/implementation-plan.md` to
   `.attune/plan-history/plan-v1.md`
3. Record version 1 in mission state

```bash
mkdir -p .attune/plan-history/feedback
cp docs/implementation-plan.md .attune/plan-history/plan-v1.md
```

### On Plan Revision

When the planning skill produces a revised plan after
feedback:

1. Copy new `docs/implementation-plan.md` to
   `.attune/plan-history/plan-v{N}.md`
2. Generate diff summary between v{N-1} and v{N}
3. Record version N in mission state

```bash
cp docs/implementation-plan.md .attune/plan-history/plan-v${N}.md
```

## Diff Summary Generation

Compare the previous and current versions section by
section. Produce a human-readable summary:

```
--- Changes in v2 (from round 1 feedback) ---
 Architecture: +12 lines, -8 lines
   Addressed: "Split API layer" -> added read/write separation
 Phase 1: unchanged
 Phase 3: +4 lines (new error handling tasks)
----------------------------------------------
```

### Algorithm

1. Split both versions by heading (`## ` or `### `)
2. For each section present in both versions:
   - If identical: report "unchanged"
   - If different: count added/removed lines, summarize
     what changed by correlating with the feedback that
     prompted the revision
3. For sections only in the new version: report "new"
4. For sections only in the old version: report "removed"

### Diff Command

```bash
diff --unified=3 \
  .attune/plan-history/plan-v${PREV}.md \
  .attune/plan-history/plan-v${CURR}.md \
  | head -100
```

## Cleanup

After execution phase completes, plan history can be
kept for retrospectives or removed:

```bash
# Optional cleanup (not automatic)
rm -rf .attune/plan-history/
```

The orchestrator does NOT auto-delete plan history.
Users decide whether to keep it.

---
name: reflexion-buffer
description: >-
  Episodic memory of phase execution failures that
  feeds typed self-critiques back into retry
  attempts, enabling within-round learning.
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
estimated_tokens: 180
---

# Reflexion Buffer

## Purpose

When a phase fails and damage-control triggers a retry,
the agent retries blind. This module maintains an
episodic memory of what was tried, what failed, and why,
so each retry sees the full failure history and avoids
repeating the same mistakes.

Based on the Reflexion pattern (Shinn et al., NeurIPS
2023): verbal self-critiques stored in a buffer provide
reinforcement across attempts without fine-tuning.

## Buffer Structure

Each phase maintains its own buffer. Entries accumulate
across retry attempts within a single iteration-governor
round.

```json
{
  "phase": "execute",
  "max_attempts": 3,
  "entries": [
    {
      "attempt": 1,
      "action": "Ran integration test suite after T012",
      "result": "Timeout after 120s on test_api_auth",
      "diagnosis": "Auth mock server not started before test invocation",
      "adjustment": "Start mock server in setup fixture, add health check before test run"
    }
  ]
}
```

### Field Definitions

| Field | Type | Description |
|-------|------|-------------|
| `phase` | string | Current phase name |
| `max_attempts` | int | Retry cap (from damage-control) |
| `entries` | array | One entry per failed attempt |
| `entries[].attempt` | int | Attempt number (1-indexed) |
| `entries[].action` | string | What was tried (concise) |
| `entries[].result` | string | What happened (error, output) |
| `entries[].diagnosis` | string | Root cause analysis |
| `entries[].adjustment` | string | Concrete change for next try |

## Context Injection Format

Before each retry, inject the full buffer into the
phase prompt. The retry MUST see all prior failures,
not just the most recent.

```
## Reflexion Buffer (Phase: {phase}, Attempt {N}/{max})

### Attempt 1: FAILED
**Action**: {action}
**Result**: {result}
**Diagnosis**: {diagnosis}
**Adjustment**: {adjustment}
```

Repeat the block for each prior attempt. One heading
block, no redundant framing.

## Integration with Phase Routing

The buffer hooks into the error handling path defined
in `modules/phase-routing.md`, step 6:

```
Phase fails
  |
  1. Classify error (existing damage-control step)
  |
  2. Build reflexion entry
  |   Extract: action, result, diagnosis, adjustment
  |   Append to buffer
  |
  3. Check convergence (see below)
  |   If converged: escalate, skip retry
  |
  4. Inject buffer into retry context
  |   Prepend buffer block to phase prompt
  |
  5. Retry phase (existing damage-control step)
```

Steps 2-4 are new. Steps 1 and 5 are the existing
damage-control flow.

## Convergence Detection

If the buffer shows the same failure repeating, retrying
is pointless. Detect convergence and escalate instead.

**Algorithm**:

```
function is_converged(entries):
    if len(entries) < 2:
        return false

    last = entries[-1]
    prev = entries[-2]

    # Same error category repeating
    if similar(last.result, prev.result) and
       similar(last.diagnosis, prev.diagnosis):
        return true

    return false
```

**Similarity check**: Compare `result` and `diagnosis`
fields. If both share the same error type or message,
the attempts are converging. Exact string matching is
sufficient; the agent will reuse phrasing for identical
root causes.

**On convergence**: Skip remaining retries:

```
Reflexion buffer detected repeated failure pattern.

  Attempt {N-1}: {diagnosis}
  Attempt {N}:   {diagnosis}

Retrying is unlikely to help. Options:
  [A] Retry anyway (override convergence detection)
  [B] Skip this phase and continue
  [C] Abort mission
```

## Buffer Lifecycle

1. **Created**: When a phase begins execution. Empty
   buffer initialized with phase name and max_attempts.

2. **Populated**: On each phase failure, before retry.
   One entry appended per failed attempt.

3. **Persisted**: Written to mission-state.json under
   the phase object on phase completion (success or
   exhaustion) for post-mission analysis.

4. **Cleared**: When the next phase begins. Prior phase
   buffers remain in mission-state.json.

### State Schema Addition

Add `reflexion_buffer` to each phase entry in
mission-state.json (same schema as the buffer structure
above). An empty `entries` array means the phase
succeeded on first attempt.

## Integration with Ralph Wiggum

When `ralph-wiggum:ralph-loop` is active, each
rejection becomes a reflexion entry:

- `action`: the completion claim
- `result`: "Rejected by ralph-loop: {reason}"
- `diagnosis`: extracted from ralph's feedback
- `adjustment`: derived from ralph's specific ask

The buffer is injected into the next ralph iteration,
preventing the agent from repeating incomplete work
that ralph already rejected.

## Self-Critique Quality

The diagnosis field must contain a root cause, not a
restatement of the error.

- **Bad**: "The test failed." (restates the result)
- **Good**: "Auth mock not initialized before test
  runner started. Setup fixture creates the mock but
  does not wait for its health endpoint."

If the root cause is unclear, say so: "Root cause
unclear. Possible: resource contention, missing async
await, or flaky external dependency." An honest "I do
not know" beats a fabricated diagnosis.

---
name: state-detection
description: Artifact existence checks, quality validation, and staleness detection for mission type selection
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
estimated_tokens: 200
---

# State Detection

## Artifact Existence Checks

The orchestrator scans for these artifacts to determine project state:

| Artifact | Path | Indicates |
|----------|------|-----------|
| Project brief | `docs/project-brief.md` | Brainstorm phase completed |
| Specification | `docs/specification.md` | Specify phase completed |
| Implementation plan | `docs/implementation-plan.md` | Plan phase completed |
| Execution state | `.attune/execution-state.json` | Execute phase in progress |

### Alternative Paths

Some projects may use non-standard paths. The orchestrator also checks:

- `project-brief.md` (root level)
- `specification.md` (root level)
- `implementation-plan.md` (root level)
- `.specify/` directory (spec-kit convention)

## Quality Validation

An artifact file must pass quality checks to be considered "complete":

### Non-Empty Check

File must contain more than just whitespace or a single heading. Minimum: 100 characters of content.

### Required Sections

| Artifact | Required Sections |
|----------|------------------|
| project-brief.md | "Problem Statement" or "Goals" |
| specification.md | "User Stories" or "Requirements" or "Functional" |
| implementation-plan.md | "Tasks" or "Phase" or "Steps" |

### Frontmatter Status

If the artifact has YAML frontmatter with a `status` field, it must be:
- `complete` or `approved`: artifact is ready
- `draft` or `in-progress`: artifact exists but is not ready (treated as non-existent for type detection)
- `rejected`: artifact should be regenerated

## Staleness Detection

Artifacts may become stale when the codebase evolves after they were written:

### Staleness Signals

| Signal | Detection | Action |
|--------|-----------|--------|
| Artifact older than 7 days | `mtime` check | Warn user, suggest refresh |
| Referenced files don't exist | Parse file paths in artifact | Warn about missing references |
| Git changes since artifact | `git log --since` | Warn about codebase drift |

### Staleness Response

Stale artifacts trigger a warning but do not block mission execution:

```
Warning: docs/specification.md was last modified 14 days ago.
The codebase has 23 commits since then.
Consider refreshing with /attune:specify before proceeding.

Continue anyway? [Y/n]
```

With `--auto` flag, stale artifacts are accepted with a logged warning.

## State Detection Result

The detection phase produces a structured result:

```json
{
  "artifacts": {
    "project_brief": {
      "exists": true,
      "path": "docs/project-brief.md",
      "quality": "valid",
      "last_modified": "2026-02-01T10:00:00Z",
      "stale": false
    },
    "specification": {
      "exists": true,
      "path": "docs/specification.md",
      "quality": "valid",
      "last_modified": "2026-02-05T14:30:00Z",
      "stale": false
    },
    "implementation_plan": {
      "exists": false
    },
    "execution_state": {
      "exists": false
    }
  },
  "detected_type": "tactical",
  "confidence": "high"
}
```

---
name: trust-tier
description: >-
  Progressive trust system that reduces user
  checkpoints for proven skills and increases
  oversight for unreliable ones.
parent_skill: attune:mission-orchestrator
category: workflow-orchestration
estimated_tokens: 200
---

# Trust Tier

## Purpose

Reduce checkpoint friction for skills that have
demonstrated competence. Trust is earned slowly through
repeated success and lost quickly on failure. This
follows the Auto MoC principle: by batch four, 95% of
fixes ran without asking permission. Experienced users
increase both autonomy and strategic interruption
(Anthropic autonomy research).

## Three Trust Tiers

| Tier | Name | Checkpoint Frequency | Qualification |
|------|------|---------------------|---------------|
| T1 | Supervised | Every phase transition | Default for all new/untracked skills |
| T2 | Guided | Critical phases only (specify, execute) | 5+ executions, >85% success rate |
| T3 | Autonomous | Start and end only | 15+ executions, >95% success rate |

## Trust Score Tracking

Track per skill in `.attune/trust-scores.json`:

```json
{
  "brainstorm": {
    "executions": 18, "successes": 17, "failures": 1,
    "tier": "T3",
    "last_promotion": "2026-03-20T14:00:00Z",
    "last_failure": "2026-02-15T10:30:00Z"
  }
}
```

**Success**: phase completed without user intervention
or rollback. **Failure**: phase required user
correction, damage-control, or rollback.

## Tier Transitions

Trust is earned slowly, lost quickly: 5 successes
to promote, 1 failure to demote.

### Promotion

Check after every successful execution:

```
function check_promotion(skill):
    record = trust_scores[skill]
    rate = record.successes / record.executions
    if record.tier == "T1"
       and record.executions >= 5
       and rate > 0.85:
        promote(skill, "T2")
    elif record.tier == "T2"
       and record.executions >= 15
       and rate > 0.95:
        promote(skill, "T3")
```

### Demotion

Immediate on any failure at T2 or T3:

```
function on_failure(skill):
    record = trust_scores[skill]
    record.failures += 1
    if record.tier == "T3":
        demote(skill, "T2")
    elif record.tier == "T2":
        demote(skill, "T1")
    # T1 stays at T1 (already maximum oversight)
```

Demotion does not reset execution counts. The skill
must re-qualify by accumulating enough successes to
restore its success rate above the threshold.

## Checkpoint Reduction Rules

| Tier | Checkpoints Shown | Checkpoints Skipped |
|------|-------------------|---------------------|
| T1 (Supervised) | All per phase-routing protocol | None |
| T2 (Guided) | specify, execute | brainstorm, plan |
| T3 (Autonomous) | Mission start (confirm intent), mission end (review results) | All intermediate phases |

The `--auto` flag overrides all tiers to T3 behavior.
This is the existing feature from phase-routing; trust
tiers provide the same outcome without the global flag.

## Integration with Phase Routing

Phase-routing step 5 (User Checkpoint) consults the
trust tier before presenting a checkpoint:

```
function should_checkpoint(phase, skill):
    tier = trust_scores[skill].tier

    # Safety checkpoints always fire (see below)
    if is_safety_checkpoint(phase):
        return true

    if tier == "T1":
        return true
    elif tier == "T2":
        return phase in ["specify", "execute"]
    elif tier == "T3":
        return false  # start/end handled by orchestrator
```

When the tier allows skipping, the orchestrator logs
the checkpoint data (for auditability) but does not
pause for user input. When the tier requires it,
the checkpoint presents as normal.

## Strategic Interruption

Even at T3, certain events always trigger a checkpoint
regardless of trust tier. Trust reduces routine
checkpoints, not safety checkpoints.

**Always-checkpoint events:**

- Destructive operations: file deletion, force push,
  branch reset
- External-facing actions: PR creation, issue comments,
  release tagging
- Scope expansion: adding features not in the original
  plan or specification
- Cost thresholds: operations exceeding estimated
  token/time budgets

```
function is_safety_checkpoint(phase_context):
    return (phase_context.has_destructive_ops
         or phase_context.has_external_actions
         or phase_context.scope_expanded
         or phase_context.budget_exceeded)
```

## State and Dashboard

Storage: `.attune/trust-scores.json` (alongside mission
state). The orchestrator reads scores at mission start
and writes updates after each phase. Scores persist
across missions; they track long-term skill reliability,
not single-mission state. If the file does not exist,
all skills default to T1.

When a mission reports progress, whether at a phase
checkpoint or on `/attune:mission --resume`, display
current trust tiers:

```
Trust Tiers:
  T3 (Autonomous): brainstorm, specify [15+ runs, 97%]
  T2 (Guided):     plan, execute [8 runs, 88%]
  T1 (Supervised): new-skill [0 runs]
```

# Mission Charter Template

Structured mission definition for coordinated agent work.

## Purpose

A Mission Charter defines the boundaries and success criteria for a
mission before execution begins. It prevents scope drift,
establishes clear completion criteria, and provides a reference
point for checkpoint reviews.

## When to Use

Use a Mission Charter when:

- Starting a new mission that will span multiple phases
- Coordinating work across multiple agents or sessions
- You need clear scope boundaries to prevent drift
- Success criteria need to be explicit and measurable
- Resource constraints (tokens, time) must be tracked

Do NOT use when:

- The task is a single, self-contained change
- Scope is obvious and doesn't need formalization
- The work is exploratory and boundaries are unknown

## Getting Started

1. Copy the template below into your mission planning document
2. Fill in the required fields: `outcome`, `success_metric`,
   `deadline`, `scope`, `stop_criteria`
3. Add optional constraints if you have token/time budgets
4. Store in `.attune/mission-state.json` or your planning document
5. Reference during checkpoint reviews to verify scope adherence

## Why This Pattern

Mission Charters prevent the common failure mode of "scope creep by
accident." Without explicit boundaries, missions tend to expand to
fill available time and tokens. The charter creates a contract that
forces explicit decisions when scope changes are proposed.

This pattern emerged from observing that agents with clear
boundaries complete missions faster and with fewer reworks than
agents who discover scope as they go.

## Template

```yaml
mission_charter:
  # REQUIRED: What success looks like
  outcome: |
    Clear description of the desired end state.
    Should be specific enough to verify completion.

  # REQUIRED: How we measure success
  success_metric: |
    Measurable criteria for mission completion.
    Example: "All tests pass, no lint errors, feature works in demo"

  # REQUIRED: Time boundary
  deadline: session | YYYY-MM-DD | "<duration>"
    # session = complete within this Claude session
    # date = absolute deadline
    # duration = relative (e.g., "2 hours", "3 days")

  # OPTIONAL: Resource and action constraints
  constraints:
    token_budget: 50000      # Maximum tokens to spend (optional)
    time_budget: "2 hours"   # Maximum time (optional)
    forbidden:               # Actions that must NOT be taken
      - "No database schema changes"
      - "No API breaking changes"

  # REQUIRED: Scope boundaries
  scope:
    in_scope:                # Areas to work on
      - "src/api/"
      - "tests/api/"
    out_of_scope:            # Areas to avoid
      - "Frontend code"
      - "Database migrations"

  # REQUIRED: Conditions that halt the mission
  stop_criteria:
    - "Token budget exceeded"
    - "Blocker identified that requires user decision"
    - "External dependency unavailable"
```

## Examples

### Example 1: Feature Implementation

```yaml
mission_charter:
  outcome: |
    Implement user authentication with JWT tokens, including
    login, logout, and token refresh endpoints.

  success_metric: |
    - All auth endpoints return correct responses
    - Token validation works for protected routes
    - Test coverage > 90% for auth module

  deadline: session

  constraints:
    token_budget: 80000
    forbidden:
      - "No changes to existing user schema"
      - "No breaking changes to public API"

  scope:
    in_scope:
      - "src/auth/"
      - "tests/auth/"
      - "docs/api/auth.md"
    out_of_scope:
      - "Frontend login UI"
      - "OAuth integration"

  stop_criteria:
    - "Token budget exceeded"
    - "Security vulnerability discovered"
    - "User requirement clarification needed"
```

### Example 2: Bug Fix

```yaml
mission_charter:
  outcome: |
    Fix the race condition in the order processing queue that
    causes duplicate orders under high load.

  success_metric: |
    - Load test with 1000 concurrent requests shows no duplicates
    - All existing tests pass
    - Fix verified in staging environment

  deadline: "2024-03-20"

  constraints:
    time_budget: "4 hours"
    forbidden:
      - "No changes to queue infrastructure"
      - "No breaking API changes"

  scope:
    in_scope:
      - "src/queue/order_processor.py"
      - "tests/queue/"
    out_of_scope:
      - "Other queue handlers"
      - "Database schema"

  stop_criteria:
    - "Root cause requires architectural changes"
    - "Fix would impact other queue handlers"
```

### Example 3: Refactoring

```yaml
mission_charter:
  outcome: |
    Extract the validation logic from the monolithic service
    class into separate validator modules following SRP.

  success_metric: |
    - All validators have single responsibility
    - Test coverage maintained or improved
    - No behavior changes (same test results)

  deadline: session

  constraints:
    token_budget: 60000
    forbidden:
      - "No public API changes"
      - "No new dependencies"

  scope:
    in_scope:
      - "src/services/order_service.py"
      - "src/validators/"
      - "tests/validators/"
    out_of_scope:
      - "Other service classes"
      - "Frontend validation"

  stop_criteria:
    - "Refactoring reveals deeper architectural issues"
    - "Tests start failing unexpectedly"
```

## Integration with Mission Orchestrator

The mission-orchestrator skill uses Mission Charters to:

1. **Initialize mission state** - Store charter in `.attune/mission-state.json`
2. **Guide phase execution** - Each phase checks scope boundaries
3. **Enable checkpoint reviews** - Progress Reports reference
   original charter
4. **Determine completion** - Success metric verified before
   mission close

## Related References

- `progress-report.md` - Checkpoint template that references
  mission charter
- `../modules/mission-types.md` - Mission type definitions
- `../modules/phase-routing.md` - Phase execution protocol

# Progress Report Template

Checkpoint status report for mission progress tracking.

## Purpose

Progress Reports provide structured checkpoints during mission
execution. They track progress, surface blockers, monitor budget
consumption, and update risk status. Use them at natural phase
boundaries or when significant changes occur.

## When to Use

Generate a Progress Report when:

- Crossing phase boundaries (brainstorm→specify→plan→execute)
- A blocker is identified that halts forward progress
- Risk level escalates (e.g., Level 1→Level 2)
- Budget thresholds reached (50%, 75%, 90% of tokens/time)
- Every 30-60 minutes for long-running missions
- User asks "what's the status?"

Do NOT generate when:

- Progress is continuous and unremarkable
- No blockers, budget concerns, or risk changes
- Less than 15 minutes since last report

## Getting Started

1. Copy the template below
2. Fill required fields: `timestamp`, `phase`, `progress`, `blockers`,
   `budget`, `risks`, `next_actions`
3. Add optional `decisions` if significant choices were made
4. Store in mission state or append to session log
5. Compare against Mission Charter to check scope adherence

## Why This Pattern

Progress Reports create a verifiable audit trail. Without them,
long missions become opaque: blockers hide, budgets silently
exhaust, and scope drifts undetected until it's too late.

The structured format forces explicit acknowledgment of:
- What's blocked (and who owns unblocking)
- How much budget remains (and whether to continue)
- What risks have changed (and whether to escalate)

This pattern emerged from observing that missions with regular
checkpoints have higher success rates and fewer "surprise failures."

## Template

```yaml
progress_report:
  # REQUIRED: When this report was generated
  timestamp: "2024-03-20T14:30:00Z"

  # REQUIRED: Current phase in the mission lifecycle
  phase: brainstorm | specify | plan | execute

  # REQUIRED: Task progress summary
  progress:
    tasks_complete: 3
    tasks_total: 8
    tasks_blocked: 1
    tasks_in_progress: 2

  # REQUIRED: Items blocking progress (empty if none)
  blockers:
    - description: "Waiting for API key from ops team"
      impact: "Cannot test production integration"
      owner: "user"
      ETA: "2024-03-21"

  # REQUIRED: Budget consumption
  budget:
    tokens_used: 45000
    tokens_budget: 80000        # null if unlimited
    time_elapsed: "1h 30m"
    time_budget: "3 hours"      # null if unlimited

  # REQUIRED: Risk status updates
  risks:
    current_readiness_level: 1  # 0-3 scale
    new_risks:
      - "Third-party API has stricter rate limits than documented"
    resolved_risks:
      - "Database migration approach validated"
    escalated_risks: []         # Risks moved to higher level

  # REQUIRED: Immediate next steps
  next_actions:
    - "Complete task T004 (API client implementation)"
    - "Resolve blocker: obtain API key"
    - "Run integration tests before checkpoint"

  # OPTIONAL: Decisions made since last report
  decisions:
    - choice: "Use Redis for caching instead of Memcached"
      rationale: "Better support for our data structures"
      alternatives_considered: ["Memcached", "In-memory"]

  # OPTIONAL: Notes for the record
  notes: |
    Discovered that the legacy API returns different error codes
    than documented. Updated test expectations accordingly.
```

## Example Reports

### Example 1: Mid-Execution Checkpoint

```yaml
progress_report:
  timestamp: "2024-03-20T14:30:00Z"
  phase: execute

  progress:
    tasks_complete: 5
    tasks_total: 12
    tasks_blocked: 0
    tasks_in_progress: 2

  blockers: []

  budget:
    tokens_used: 52000
    tokens_budget: 100000
    time_elapsed: "2h 15m"
    time_budget: "4 hours"

  risks:
    current_readiness_level: 1
    new_risks: []
    resolved_risks:
      - "API authentication approach confirmed working"
    escalated_risks: []

  next_actions:
    - "Complete T006: Add pagination to list endpoint"
    - "Complete T007: Write integration tests"
    - "Review all API endpoints for consistency"

  decisions:
    - choice: "Use cursor-based pagination"
      rationale: "Better performance for large datasets"
      alternatives_considered: ["Offset-based pagination"]

  notes: |
    All API endpoints now return consistent error responses.
    Ready to proceed with frontend integration.
```

### Example 2: Blocked Checkpoint

```yaml
progress_report:
  timestamp: "2024-03-20T16:00:00Z"
  phase: execute

  progress:
    tasks_complete: 7
    tasks_total: 12
    tasks_blocked: 2
    tasks_in_progress: 0

  blockers:
    - description: "Database migration requires DBA approval"
      impact: "Cannot test schema changes in staging"
      owner: "DBA team"
      ETA: "2024-03-21T10:00:00Z"
    - description: "Feature flag not configured in production"
      impact: "Cannot verify production behavior"
      owner: "Platform team"
      ETA: "2024-03-21"

  budget:
    tokens_used: 68000
    tokens_budget: 100000
    time_elapsed: "3h 45m"
    time_budget: "4 hours"

  risks:
    current_readiness_level: 2
    new_risks:
      - "Time budget nearly exhausted with blockers pending"
    resolved_risks: []
    escalated_risks: []

  next_actions:
    - "Follow up with DBA team on migration approval"
    - "Request feature flag configuration from platform"
    - "Document current state for handoff if needed"

  decisions: []

  notes: |
    Mission paused pending external dependencies.
    All implementable tasks complete. Ready to resume
    once blockers clear.
```

### Example 3: Risk Escalation Checkpoint

```yaml
progress_report:
  timestamp: "2024-03-20T11:00:00Z"
  phase: plan

  progress:
    tasks_complete: 2
    tasks_total: 5
    tasks_blocked: 0
    tasks_in_progress: 1

  blockers: []

  budget:
    tokens_used: 25000
    tokens_budget: 80000
    time_elapsed: "45m"
    time_budget: "2 hours"

  risks:
    current_readiness_level: 2  # Escalated from 1
    new_risks: []
    resolved_risks: []
    escalated_risks:
      - risk: "Authentication changes affect production users"
        from_level: 1
        to_level: 2
        reason: "Discovered 10x more active users than expected"

  next_actions:
    - "Request war-room checkpoint for Level 2 review"
    - "Complete implementation plan with additional controls"
    - "Add staged rollout to plan"

  decisions:
    - choice: "Add feature flag for gradual rollout"
      rationale: "Mitigates risk of widespread auth failure"
      alternatives_considered: ["Direct deploy", "Canary only"]

  notes: |
    Discovered production user count is 10x higher than
    documented. Escalating to Level 2 for additional controls.
```

## Checkpoint Rhythm

When to generate Progress Reports:

1. **Phase boundaries**: Between brainstorm→specify→plan→execute
2. **Blocker identification**: When progress is blocked
3. **Risk escalation**: When readiness level increases
4. **Budget thresholds**: At 50%, 75%, 90% budget consumption
5. **Time intervals**: Every 30-60 minutes for long missions
6. **User request**: When user asks for status

## Integration with Mission Charter

Progress Reports reference the original Mission Charter:

```yaml
mission_charter_ref: "docs/project-brief.md"
charter_status:
  outcome_progress: "60% complete"
  success_metric_status: "On track"
  constraints_status: "Within budget, no forbidden actions"
  scope_adherence: "No scope drift detected"
```

## Integration with Mission Orchestrator

The mission-orchestrator skill uses Progress Reports to:

1. **Track phase progress** - Update mission state with task
   completion
2. **Surface blockers** - Alert user to items requiring attention
3. **Monitor budget** - Warn when approaching limits
4. **Update risk status** - Adjust readiness level as needed

## Related References

- `mission-charter.md` - Original mission definition
- `../modules/mission-state.md` - State persistence schema
- `../../project-execution/references/mission-report.md` - Final mission report