forge-orkes 0.1.0

package/template/.forge/templates/framework-absorption/gsd.md

@@ -0,0 +1,174 @@
+# GSD → Forge Absorption Reference
+
+This file is read by the `forge` skill during brownfield init when GSD is detected.
+It provides the mapping tables needed to convert GSD documentation to Forge format.
+
+## Detection Signatures
+
+```
+agents/gsd-*.md                    # Agent files prefixed with gsd-
+commands/gsd/                      # Command definitions directory
+get-shit-done/                     # Framework directory
+Root-level: PROJECT.md + REQUIREMENTS.md + ROADMAP.md + STATE.md
+CONTEXT.md with "NON-NEGOTIABLE" or "DEFERRED" sections
+```
+
+## File Conversion Map
+
+| GSD Source | Forge Target | Conversion Notes |
+|-----------|-------------|-----------------|
+| `PROJECT.md` | `.forge/project.yml` | Extract project name, description, tech stack, goals. Convert prose to YAML structure. |
+| `REQUIREMENTS.md` | `.forge/requirements.yml` | Assign FR-IDs to each requirement. Convert acceptance criteria to Given/When/Then. Mark unknowns as `[NEEDS CLARIFICATION]`. |
+| `ROADMAP.md` | `.forge/roadmap.yml` | Extract phases, milestones. Add dependency references between phases. Convert to YAML. |
+| `STATE.md` | `.forge/state/index.yml` + `.forge/state/milestone-{id}.yml` | Extract current phase number, progress, active blockers, recent decisions. Split into global index and per-milestone state. |
+| `CONTEXT.md` | `.forge/context.md` | NON-NEGOTIABLE → Locked Decisions. DEFERRED → Deferred Ideas. DISCRETION → Discretion Areas. Minimal format change needed. |
+| `PLAN.md` | `.forge/phases/{N}-{name}/plan.md` | Keep XML task format. Add `must_haves` YAML frontmatter. Split per-phase if combined. |
+| `references/ui-brand.md` | `.forge/design-system.md` | Extract component rules, brand guidelines. Convert to component mapping table format. |
+| `references/tdd.md` | `.forge/constitution.md` Article II | Inform Test-First article gates with project-specific testing approach. |
+| `references/verification-patterns.md` | Informs `verifying` skill | Extract project-specific verification patterns. Add to constitution or context. |
+| `references/git-integration.md` | Informs `.claude/settings.json` | Extract commit format rules. Configure hooks if custom. |
+| `.planning/quick/` | `.forge/archive/gsd/quick/` + `.forge/context.md` | Archive all quick task directories intact. Extract key decisions and context into `.forge/context.md` under "Absorbed Quick Tasks." See Quick Task Absorption below. |
+| `STATE.md` → Quick Tasks Completed table | `.forge/state/milestone-{id}.yml` | Preserve the completion table as `quick_tasks_history` in the milestone state file for reference. |
+
+## Agent Mapping
+
+| GSD Agent | Forge Equivalent | Notes |
+|-----------|-----------------|-------|
+| gsd-planner | `planner` agent | Add constitutional gate enforcement. |
+| gsd-executor | `executor` agent | Same deviation rules. Add context engineering. |
+| gsd-debugger | `debugging` skill | Not a separate agent in Forge — invoked as skill. |
+| gsd-verifier | `verifier` agent | Same goal-backward approach. |
+| gsd-codebase-mapper | `researcher` agent | Codebase research type. |
+| gsd-plan-checker | `planner` agent | Plan quality check built into planning skill. |
+| gsd-integration-checker | `verifier` agent | Key Links verification. |
+| gsd-project-researcher | `researcher` agent | Requirements research type. |
+| gsd-research-synthesizer | `researcher` agent | Technology research type. |
+| gsd-phase-researcher | `researcher` agent | Feasibility research type. |
+| gsd-roadmapper | `planner` agent | Roadmap creation is part of planning skill. |
+
+## Command Mapping
+
+| GSD Commands | Forge Skill |
+|-------------|-------------|
+| Commands 1-5 (project init) | `forge` — tier detection replaces manual command selection |
+| Commands 6-10 (research) | `researching` |
+| Commands 11-15 (planning) | `planning` |
+| Commands 16-20 (execution) | `executing` |
+| Commands 21-25 (verification) | `verifying` |
+| Commands 26-28 (utilities) | `quick-tasking`, `debugging` |
+
+## Quick Task Absorption
+
+GSD quick tasks live in `.planning/quick/{id}-{slug}/` and each can contain PLAN, SUMMARY, CONTEXT, RESEARCH, and VERIFICATION artifacts. These represent real work with real decisions — they must not be silently dropped during absorption.
+
+### Process
+
+**Step 1: Archive intact**
+
+Copy the entire `.planning/quick/` directory to `.forge/archive/gsd/quick/`. This preserves all artifacts in their original structure so nothing is lost.
+
+```
+.planning/quick/ → .forge/archive/gsd/quick/
+```
+
+**Step 2: Extract decisions into context**
+
+Read each quick task's artifacts (prioritize SUMMARY > CONTEXT > RESEARCH) and extract:
+- **Decisions made** — implementation choices, library selections, approach rationale
+- **Knowledge gained** — gotchas discovered, patterns established, constraints identified
+- **Refactoring items** — any quick tasks tagged as refactoring work → add to `.forge/refactor-backlog.yml`
+
+Write extracted decisions to `.forge/context.md` under an "Absorbed Quick Tasks" section:
+
+```markdown
+## Absorbed Quick Tasks
+
+Decisions and context extracted from {N} GSD quick tasks during framework absorption.
+Full artifacts archived at `.forge/archive/gsd/quick/`.
+
+### Key Decisions
+- [{id}] {description}: {decision or outcome}
+- [{id}] {description}: {decision or outcome}
+
+### Patterns Established
+- {pattern description} (from quick tasks {id}, {id})
+
+### Carried Forward to Refactor Backlog
+- {refactoring item} (from quick task {id})
+```
+
+**Step 3: Preserve completion history**
+
+Extract the "Quick Tasks Completed" table from `STATE.md` and include it in the milestone state file as `quick_tasks_history`:
+
+```yaml
+quick_tasks_history:
+  - id: "{quick_id}"
+    description: "{description}"
+    date: "{date}"
+    commit: "{hash}"
+    status: "{status if present}"
+```
+
+This allows Forge to reference what was done without re-reading archived artifacts.
+
+### What NOT to do
+
+- Don't discard quick task artifacts — even trivial-looking tasks may contain decisions that inform future work
+- Don't flatten all quick tasks into a single summary — preserve individual task identity so specific decisions can be traced back
+- Don't promote all quick tasks to the refactor backlog — only those explicitly tagged as refactoring work
+
+## What Carries Forward Unchanged
+
+These GSD patterns are preserved in Forge. During absorption, validate they're still configured:
+
+- **Context engineering** — Size gates (project < 5KB, requirements < 50KB, plan < 30KB)
+- **Deviation rules 1-4** — Same logic, same priority order
+- **Goal-backward verification** — 3 levels: truths → artifacts → key links
+- **Atomic commits** — `{type}({scope}): {description}`, never `git add .`
+- **Wave-based execution** — Dependency analysis → wave grouping → parallel tasks
+- **Fresh agent pattern** — Spawn fresh agents for 20+ file tasks
+
+## What's New (Not in GSD)
+
+During absorption, offer to enable these Forge capabilities that GSD lacks:
+
+- **Constitutional governance** — Suggest articles based on GSD's implicit rules
+- **Design system enforcement** — If `references/ui-brand.md` exists, convert to design-system.md
+- **Native hooks** — Auto-test on file write, commit format validation
+- **Architecture Decision Records** — Capture existing decisions as ADRs
+- **Structured requirements** — YAML with IDs and Given/When/Then criteria
+
+## Codebase Verification (Critical)
+
+GSD documentation drifts. Always verify against the actual codebase before converting:
+
+| GSD Doc Claim | Verify By |
+|--------------|-----------|
+| Tech stack in PROJECT.md | Cross-check `package.json`, actual imports |
+| Features in REQUIREMENTS.md | Check if corresponding routes/components/tests exist |
+| Phase completion in STATE.md | Verify features are wired and working (not stubs) |
+| Design system in references/ui-brand.md | Grep src/ for actual component usage — are library components used consistently? |
+| Decisions in CONTEXT.md | Check if NON-NEGOTIABLE rules are actually followed in code |
+| Quick task completions in STATE.md | Verify commits exist (`git log --oneline {hash}`). Check that claimed changes are present in the codebase. |
+
+Flag any discrepancies to the user. The codebase is the source of truth, not the docs.
+
+## Absorption Checklist
+
+- [ ] All GSD state files read and content extracted
+- [ ] **Documentation verified against actual codebase** (discrepancies flagged)
+- [ ] Project info converted to `.forge/project.yml`
+- [ ] Requirements converted to `.forge/requirements.yml` with IDs
+- [ ] Roadmap converted to `.forge/roadmap.yml`
+- [ ] Current state captured in `.forge/state/` (index.yml + milestone files, verified against code reality)
+- [ ] Context/decisions preserved in `.forge/context.md`
+- [ ] Design/brand rules converted to `.forge/design-system.md` (if applicable)
+- [ ] Reference docs reviewed for constitution-worthy rules
+- [ ] Quick task artifacts archived intact in `.forge/archive/gsd/quick/`
+- [ ] Quick task decisions extracted to `.forge/context.md` under "Absorbed Quick Tasks"
+- [ ] Quick task refactoring items added to `.forge/refactor-backlog.yml` (if any)
+- [ ] Quick task completion history preserved in milestone state as `quick_tasks_history`
+- [ ] Unresolved discrepancies logged in `.forge/context.md` under "Needs Resolution"
+- [ ] Original GSD files archived in `.forge/archive/gsd/`
+- [ ] User confirmed conversion results

package/template/.forge/templates/framework-absorption/spec-kit.md

@@ -0,0 +1,52 @@
+# Spec-Kit → Forge Absorption Reference
+
+This file is read by the `forge` skill during brownfield init when Spec-Kit is detected.
+
+## Detection Signatures
+
+```
+spec-driven.md                     # Core methodology file
+templates/spec-template.md         # Spec template
+templates/constitution-template.md # Constitutional template
+extensions/catalog.json            # Extension system
+AGENTS.md                          # Agent definitions
+```
+
+## File Conversion Map
+
+| Spec-Kit Source | Forge Target | Conversion Notes |
+|----------------|-------------|-----------------|
+| `spec-driven.md` | `.forge/constitution.md` | Extract governance rules. Map to Forge's 9 articles or create project-specific ones. |
+| `templates/spec-template.md` | `.forge/requirements.yml` | Convert spec structure to YAML requirements with IDs. |
+| `templates/constitution-template.md` | `.forge/constitution.md` | Merge with Forge's article template. Preserve project-specific gates. |
+| Filled-in specs (project-specific) | `.forge/project.yml` + `.forge/requirements.yml` | Extract project info and requirements separately. |
+| `extensions/` configs | `.claude/skills/` | Evaluate each extension. Create Forge skills for valuable ones. |
+| `AGENTS.md` | `.claude/agents/` | Map agent definitions to Forge's 5 agents. |
+| `templates/checklist-template.md` | Informs verification skill | Extract checklist patterns for verifier. |
+| `templates/tasks-template.md` | `.forge/templates/plan.md` | Inform task template format. |
+
+## What Carries Forward
+
+- **Constitutional governance** — Spec-Kit's core strength. Directly maps to Forge's constitution.
+- **Template-driven behavior** — Forge uses templates similarly, just in YAML where machine-readable.
+- **Structured specs** — Maps to Forge's requirements.yml with Given/When/Then.
+- **`[NEEDS CLARIFICATION]` markers** — Identical concept in Forge.
+
+## What's New (Not in Spec-Kit)
+
+- **Context engineering** — Size gates, fresh agent spawning (from GSD)
+- **Deviation rules** — Structured handling of plan divergence
+- **Goal-backward verification** — 3-level verification (from GSD)
+- **Tier detection** — Auto-scaling ceremony to task complexity
+- **Design system enforcement** — Component mapping tables
+- **Native hooks** — Automated quality gates
+
+## Absorption Checklist
+
+- [ ] Spec-driven governance rules extracted and mapped to constitution articles
+- [ ] Project specs converted to project.yml and requirements.yml
+- [ ] Constitutional articles merged (Spec-Kit's + Forge's template)
+- [ ] Extensions evaluated for skill conversion
+- [ ] Agent definitions mapped to Forge's 5 agents
+- [ ] Original Spec-Kit files archived in `.forge/archive/spec-kit/`
+- [ ] User confirmed conversion results

package/template/.forge/templates/plan.md

@@ -0,0 +1,84 @@
+# Phase Plan Template
+
+Copy to `.forge/phases/{N}-{name}/plan-{NN}.md` for each plan in a phase.
+
+---
+
+```yaml
+# Plan Frontmatter — parsed by agents
+milestone: 1                            # Milestone ID from roadmap
+milestone_name: ""                      # Human-readable milestone name
+phase: 1
+phase_name: ""
+plan: 1
+type: execute                        # execute | tdd
+wave: 1                              # Execution wave (1 = no dependencies)
+depends_on: []                       # Plan IDs that must complete first
+autonomous: true                     # false if contains checkpoints
+
+must_haves:
+  truths:                            # Observable from user perspective when plan is done
+    - ""                             # e.g., "User can see their profile page"
+    - ""                             # e.g., "API returns user data as JSON"
+  artifacts:                         # Files that must exist and be substantive (not stubs)
+    - path: ""                       # e.g., "src/components/Profile.tsx"
+      provides: ""                   # e.g., "User profile display with avatar and bio"
+      min_lines: 30                  # Stub detection threshold
+  key_links:                         # Critical connections between artifacts
+    - from: ""                       # e.g., "src/components/Profile.tsx"
+      to: ""                         # e.g., "/api/users/[id]"
+      via: ""                        # e.g., "fetch in useEffect"
+      pattern: ""                    # e.g., "fetch.*api/users"
+```
+
+## Tasks
+
+<!-- Each task: 15-60 minutes of Claude execution time. 2-3 tasks per plan max. -->
+
+<task type="auto">
+  <name>Action-oriented task name</name>
+  <files>
+    - src/path/to/file.tsx (create)
+    - src/path/to/other.ts (modify)
+  </files>
+  <action>
+    Specific implementation instructions.
+    Include WHAT to build, HOW to build it, and what to AVOID (with WHY).
+    Reference context.md locked decisions where relevant.
+  </action>
+  <verify>
+    Command or check to prove completion:
+    - `npm test -- --filter=Profile`
+    - Inspect: file exists and exports component
+  </verify>
+  <done>
+    Measurable acceptance criteria:
+    - Component renders without errors
+    - Tests pass
+    - Follows design system (PrimeReact components used)
+  </done>
+</task>
+
+<!-- Checkpoint task example (use sparingly — 90% of tasks should be auto) -->
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Description of what was automated</what-built>
+  <how-to-verify>
+    1. Open http://localhost:3000/profile
+    2. Check that avatar displays correctly
+    3. Verify responsive layout on mobile
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+
+## Dependency Notes
+
+<!-- How this plan connects to others in the phase -->
+- This plan creates [X] which plan-02 depends on for [Y]
+- This plan assumes [Z] from plan-01 is complete
+
+## Context Compliance
+
+<!-- Self-check: do tasks honor locked decisions from context.md? -->
+- [ ] Every locked decision has corresponding task(s)
+- [ ] No task implements a deferred idea
+- [ ] Discretion areas handled with documented rationale

package/template/.forge/templates/project.yml

@@ -0,0 +1,40 @@
+# Forge Project Template
+# Copy to .forge/project.yml and customize. Keep under 5 KB.
+# This file answers: WHAT are we building and WHY?
+
+project:
+  name: ""                          # Project or feature name
+  description: ""                   # 2-3 sentence summary of what we're building
+  primary_goal: ""                  # The single most important outcome
+
+tech_stack:
+  language: ""                      # e.g., TypeScript, Python
+  framework: ""                     # e.g., React, Next.js, FastAPI
+  database: ""                      # e.g., PostgreSQL, SQLite, none
+  testing: ""                       # e.g., Vitest, Jest, Pytest
+  other: []                         # Additional key dependencies
+
+design_system:
+  library: ""                       # e.g., PrimeReact, Material-UI, shadcn/ui, Ant Design, Chakra UI, none
+  version: ""                       # e.g., 10.x, 5.x
+  icon_set: ""                      # e.g., PrimeIcons, Material Icons, Lucide, none
+  layout_system: ""                 # e.g., PrimeFlex, MUI Grid, Tailwind, CSS Grid
+  theme_approach: ""                # e.g., SCSS variables, CSS-in-JS, Tailwind config, design tokens
+  docs_url: ""                      # e.g., https://primereact.org/datatable/
+  # Component mapping lives in .forge/design-system.md (generated during init)
+
+constraints:
+  time: ""                          # e.g., "4 hours", "2 days", "1 week"
+  scope: ""                         # e.g., "v1 MVP", "single feature", "full system"
+  must_not:                         # Explicit exclusions
+    - ""                            # e.g., "No custom auth — use Clerk"
+    - ""                            # e.g., "No server-side rendering"
+
+success_criteria:                   # How do we know we're done?
+  - ""                              # e.g., "User can create and edit posts"
+  - ""                              # e.g., "All tests pass with >80% coverage"
+  - ""                              # e.g., "Page load < 2 seconds"
+
+risks:                              # What could go wrong?
+  - risk: ""
+    mitigation: ""

package/template/.forge/templates/refactor-backlog.yml

@@ -0,0 +1,16 @@
+# Forge Refactor Backlog
+# Auto-managed by the refactoring skill. Items added after milestone audits.
+# Work items via quick-tasking (effort: quick) or Standard tier (effort: standard).
+
+items:
+  - id: R001                             # Sequential ID: R001, R002, ...
+    milestone: 1                         # Milestone that produced this item
+    category: duplication                # duplication | complexity | naming | inconsistency | dead-code | abstraction
+    file: "src/example.ts"               # File where the issue lives
+    lines: "42-67"                       # Line range
+    description: "Brief description of the refactoring opportunity"
+    effort: quick                        # quick (< 30 min, < 50 lines) | standard (needs planning)
+    suggested_approach: "Concrete suggestion for how to address it"
+    status: pending                      # pending | in_progress | done | dismissed
+    added: "2026-01-01"                  # ISO 8601 date when added
+    completed: null                      # ISO 8601 date when done, null otherwise

package/template/.forge/templates/requirements.yml

@@ -0,0 +1,49 @@
+# Forge Requirements Template
+# Copy to .forge/requirements.yml and customize. Keep under 50 KB.
+# Mark uncertain items with [NEEDS CLARIFICATION] — planning blocks until resolved.
+
+version: "v1"                        # v1 = MVP, v2 = next iteration
+
+functional:
+  # Each requirement: unique ID, description, acceptance criteria, phase assignment
+  - id: FR-001
+    description: ""                  # Clear, testable statement
+    acceptance:                      # Given/When/Then format
+      - given: ""
+        when: ""
+        then: ""
+    phase: null                      # Assigned during roadmap creation
+    priority: P1                     # P1 = must-have, P2 = should-have, P3 = nice-to-have
+    status: pending                  # pending | clarifying | planned | implemented | verified
+    notes: ""                        # [NEEDS CLARIFICATION] if uncertain
+
+  - id: FR-002
+    description: ""
+    acceptance:
+      - given: ""
+        when: ""
+        then: ""
+    phase: null
+    priority: P1
+    status: pending
+    notes: ""
+
+non_functional:
+  - id: NFR-001
+    category: performance            # performance | security | accessibility | reliability
+    description: ""                  # e.g., "API response time < 200ms p95"
+    measurement: ""                  # How to verify this is met
+    priority: P1
+    status: pending
+
+deferred:                            # Explicitly out of scope for this version
+  - id: DEF-001
+    description: ""                  # What we're NOT building
+    reason: ""                       # Why it's deferred
+    revisit: "v2"                    # When to reconsider
+
+traceability:
+  # Populated during planning — maps requirements to phases and plans
+  # FR-001 → Phase 1, Plan 01, Tasks 1-3
+  # FR-002 → Phase 2, Plan 01, Tasks 1-2
+  mapping: []

package/template/.forge/templates/roadmap.yml

@@ -0,0 +1,44 @@
+# Forge Roadmap Template
+# Copy to .forge/roadmap.yml and customize.
+# Phases are delivery boundaries — coherent, verifiable capabilities.
+
+roadmap:
+  # Milestones group phases into concurrent work streams.
+  # Phases keep global IDs. Milestones reference them.
+  # Different milestones can be worked on in parallel across sessions.
+  milestones:
+    - id: 1
+      name: ""                         # e.g., "MVP", "Admin Dashboard"
+      phases: []                       # List of phase IDs belonging to this milestone
+
+  phases:
+    - id: 1
+      name: ""                       # e.g., "Foundation & Architecture"
+      goal: ""                       # Outcome, not task. "Users can X" not "Build Y"
+      requirements: []               # List of FR-IDs this phase delivers
+      dependencies: []               # Phase IDs that must complete first
+      success_criteria:              # Observable truths when phase is done
+        - ""                         # e.g., "User can see the landing page"
+        - ""                         # e.g., "API returns valid JSON for /users"
+      estimated_hours: null
+      status: pending                # pending | researching | planning | executing | verifying | complete
+
+    - id: 2
+      name: ""
+      goal: ""
+      requirements: []
+      dependencies: [1]              # Depends on phase 1
+      success_criteria:
+        - ""
+      estimated_hours: null
+      status: pending
+
+  # Coverage check: every FR-ID in requirements.yml must appear in exactly one phase.
+  # Orphaned requirements = planning failure.
+  coverage_verified: false
+
+  # Wave analysis: phases with no dependencies can run in parallel (Wave 1).
+  # Phases depending only on Wave 1 are Wave 2, etc.
+  waves:
+    1: []                            # Populated during planning
+    2: []

package/template/.forge/templates/state/index.yml

@@ -0,0 +1,51 @@
+# Forge Global State — Cross-Milestone Index
+# Auto-managed by agents. Do not edit manually unless recovering from errors.
+# This file tracks global concerns. Per-milestone state lives in state/milestone-{id}.yml.
+
+milestones:                            # Active milestones and their high-level status
+  - id: 1
+    name: ""                           # Human-readable milestone name from roadmap
+    status: not_started                # not_started | active | complete
+    last_updated: null                 # ISO 8601 timestamp — used for resume default selection
+
+metrics:
+  total_commits: 0
+  total_files_modified: 0
+  verification_passes: 0
+  verification_failures: 0
+  checkpoints_hit: 0
+
+# Desire Paths — Patterns in how the framework is actually used
+# Collected automatically by agents. Reviewed during verification retrospective.
+# When a pattern appears 3+ times, it becomes a candidate for framework evolution.
+# Desire paths are GLOBAL — they track framework usage across all milestones.
+desire_paths:
+  deviation_patterns: []               # Repeated Rule 1/2/3 deviations (same type, same area)
+    # - pattern: ""                    # e.g., "Rule 2: missing null checks in API handlers"
+    #   occurrences: 0
+    #   first_seen: null
+    #   last_seen: null
+
+  tier_overrides: []                   # User overriding auto-detected tier
+    # - detected: ""                   # What Forge detected
+    #   overridden_to: ""              # What user chose instead
+    #   reason: ""                     # Why (if stated)
+
+  skipped_steps: []                    # Steps users consistently skip or rush through
+    # - step: ""                       # e.g., "constitutional gate check"
+    #   skill: ""
+    #   times_skipped: 0
+
+  recurring_friction: []               # Same problem appearing across sessions
+    # - description: ""                # e.g., "Design system violations in form components"
+    #   occurrences: 0
+    #   related_files: []
+
+  agent_struggles: []                  # Tasks where agents consistently fail or need retries
+    # - task_type: ""                  # e.g., "Responsive layout implementation"
+    #   failure_pattern: ""
+    #   occurrences: 0
+
+  user_corrections: []                 # User correcting agent output in the same way repeatedly
+    # - correction: ""                 # e.g., "Always adds 'use client' directive"
+    #   occurrences: 0

package/template/.forge/templates/state/milestone.yml

@@ -0,0 +1,42 @@
+# Forge Milestone State — Per-Milestone Cursor
+# Auto-managed by agents. Do not edit manually unless recovering from errors.
+# Copy to .forge/state/milestone-{id}.yml for each active milestone.
+# This file tracks one milestone's position. Global state lives in state/index.yml.
+
+milestone:
+  id: null                             # Milestone ID from roadmap
+  name: ""                             # Human-readable milestone name
+
+current:
+  tier: null                           # quick | standard | full
+  phase: null                          # Phase number from roadmap
+  phase_name: ""                       # Human-readable phase name
+  plan: null                           # Current plan number within phase
+  task: null                           # Current task number within plan
+  status: not_started                  # not_started | researching | discussing | planning | executing | verifying | auditing | refactoring | complete
+
+progress:
+  phases_complete: 0
+  phases_total: 0
+  current_phase_percent: 0
+  overall_percent: 0
+  last_update: null                    # ISO 8601 timestamp
+
+decisions:                             # Locked decisions (synced from context.md)
+  - decision: ""
+    locked_at: null
+    rationale: ""
+
+blockers:                              # Active blockers preventing progress
+  - blocker: ""
+    type: ""                           # technical | decision | external | human-action
+    since: null
+    resolution: ""
+
+deviations:                            # Tracked deviations during execution
+  - rule: null                         # 1, 2, 3, or 4
+    description: ""
+    phase: null
+    plan: null
+    task: null
+    resolution: ""