@duypham93/openkit 0.2.0

package/context/core/code-quality.md

@@ -0,0 +1,42 @@
+# Code Quality Standards — Open Kit
+
+All implementation agents MUST follow these standards before writing any code.
+
+## Import Discipline
+- Import only what a file uses
+- Prefer explicit imports over wildcard imports
+- Remove unused imports in the same change that introduces them
+
+## Formatting
+- Consistent indentation per language convention
+- No unrelated file reformatting
+- Follow the project's existing formatter if one exists
+
+## Type Discipline
+- Prefer explicit types, schemas, or contracts
+- Avoid broad `any`-style escapes; document exceptions
+- Make nullability, optional fields, and error cases explicit
+
+## Naming
+- Descriptive names that reflect domain intent
+- No abbreviations unless ecosystem-standard
+- Match existing naming patterns before introducing new ones
+
+## Function & File Scope
+- One primary responsibility per file
+- Functions small enough that intent is obvious
+- Split large mixed-responsibility units into smaller ones
+
+## Error Handling
+- Fail loudly so the next agent can diagnose the issue
+- Do not swallow errors without recording why it is safe
+- Return or raise structured errors when the stack supports it
+
+## Tests
+- Add or update tests when behavior changes
+- Prefer tests that validate behavior, not implementation details
+- If no test framework exists, describe the missing validation path in your report
+
+## Documentation
+- Update relevant docs when commands, workflows, or architecture change
+- Do not leave future agents to infer decisions from code alone

package/context/core/issue-routing.md

@@ -0,0 +1,85 @@
+# Issue Routing
+
+This file defines how QA findings are classified and routed.
+
+For the canonical workflow contract, including lane semantics, stage order, escalation policy, and artifact expectations, use `context/core/workflow.md`.
+
+Classification is shared across all workflow modes, but routing behavior depends on the active work item mirrored through `.opencode/workflow-state.json`.
+
+## Required Issue Schema
+
+Each issue should record:
+
+- `issue_id`
+- `title`
+- `type`: `bug` | `design_flaw` | `requirement_gap`
+- `severity`: `critical` | `high` | `medium` | `low`
+- `rooted_in`: `implementation` | `architecture` | `requirements`
+- `recommended_owner`
+- `evidence`
+- `artifact_refs`
+
+## Ownership Rules
+
+| Type | Default Owner |
+| --- | --- |
+| `bug` | `FullstackAgent` |
+| `design_flaw` | `ArchitectAgent` |
+| `requirement_gap` | `BAAgent` |
+
+## Routing By Mode
+
+### Quick Task routing
+
+| Type | Route to | Expected action |
+| --- | --- | --- |
+| `bug` | `quick_build` / `FullstackAgent` | Fix in quick mode and re-verify |
+| `design_flaw` | `full_intake` / `MasterOrchestrator` | Escalate to full delivery |
+| `requirement_gap` | `full_intake` / `MasterOrchestrator` | Escalate to full delivery |
+
+Quick mode must not absorb design or requirements work. When either appears, quick execution stops and the work is promoted to the full lane.
+
+With the stronger quick-lane semantics now live, quick work includes an explicit `quick_plan` stage, but that stronger quick lane does not relax the design/requirements guardrail.
+
+Quick-mode guardrail:
+
+- do not invent a quick task board, per-task owners, or QA-per-subtask routing
+
+### Full Delivery routing
+
+| Type | Route to | Expected action |
+| --- | --- | --- |
+| `bug` | `full_implementation` / `FullstackAgent` | Fix implementation and return to QA |
+| `design_flaw` | `full_architecture` / `ArchitectAgent` | Repair the design or escalate implementation concerns through architecture review |
+| `requirement_gap` | `full_spec` / `BAAgent` | Clarify or repair requirements |
+
+Task-aware full-delivery note:
+
+- full-delivery execution tasks may carry task-local owners and findings, but routing still resolves to the feature-level stage owner above
+- task-local rework may stay within the task board only for implementation-rooted bugs that do not require a stage change
+- when a QA finding reveals a design flaw or requirement gap, the feature returns to `full_architecture` or `full_spec` even if the finding started from one execution task
+- preserve task ids and task evidence in issue notes so the orchestrator can reconnect feature routing with task-board state
+
+### Migration routing
+
+| Type | Route to | Expected action |
+| --- | --- | --- |
+| `bug` | `migration_upgrade` / `FullstackAgent` | Fix upgrade fallout and re-verify |
+| `design_flaw` | `migration_strategy` / `TechLeadAgent` | Rework upgrade sequencing, compatibility assumptions, or rollback plan |
+| `requirement_gap` | `full_intake` / `MasterOrchestrator` | Escalate into full delivery because the issue is no longer primarily technical migration work |
+
+Migration mode treats compatibility or upgrade-path mistakes as migration-stage work, but it must not absorb product-definition ambiguity.
+
+Migration-mode guardrail:
+
+- do not invent a migration task board, per-task owners, or QA-per-subtask routing in the current live contract
+
+## Retry And Escalation
+
+- Increment `retry_count` when the same issue cycles back after a failed fix
+- In quick mode, repeated `bug` failures still stay in quick mode unless a design or requirement problem is uncovered and the work is no longer safely bounded
+- In quick mode, `design_flaw` and `requirement_gap` escalate immediately rather than retrying inside quick mode
+- In migration mode, repeated `bug` failures still stay in migration mode unless product ambiguity is uncovered and the work no longer fits migration semantics
+- In migration mode, `requirement_gap` escalates immediately to full delivery instead of retrying inside migration mode
+- In full mode, repeated task-local failures may keep a task in local rework only while the issue remains implementation-rooted and stage ownership does not need to change
+- Escalate to the user after 3 failed loops on the same issue family

package/context/core/lane-selection.md

@@ -0,0 +1,54 @@
+# Lane Selection
+
+This file is the detailed routing reference for choosing between `Quick Task`, `Migration`, and `Full Delivery`.
+
+Use `context/core/workflow.md` for the canonical live contract. Use this file when you need the stricter routing rubric, tie-breakers, anti-patterns, and examples.
+
+## Core Rule
+
+Choose the lane by the dominant uncertainty of the work, not by estimated size alone.
+
+- `Quick Task`: low local uncertainty inside already-understood behavior
+- `Migration`: compatibility uncertainty inside behavior-preserving modernization
+- `Full Delivery`: product, requirements, acceptance, or cross-boundary solution uncertainty
+
+## Routing Profile Dimensions
+
+Record and reason with these dimensions:
+
+- `work_intent`: `maintenance`, `modernization`, `feature`
+- `behavior_delta`: `preserve`, `extend`, `redefine`
+- `dominant_uncertainty`: `low_local`, `compatibility`, `product`
+- `scope_shape`: `local`, `adjacent`, `cross_boundary`
+
+Expected combinations:
+
+- `Quick Task` -> `maintenance`, `preserve`, `low_local`, `local|adjacent`
+- `Migration` -> `modernization`, `preserve`, `compatibility`, `local|adjacent|cross_boundary`
+- `Full Delivery` -> usually `feature`, `extend|redefine`, `product`, often `cross_boundary`
+
+## Tie-Breaker Priority
+
+Apply these in order:
+
+1. If `behavior_delta` is not `preserve`, choose `Full Delivery`.
+2. If `dominant_uncertainty` is `product`, choose `Full Delivery`.
+3. If `dominant_uncertainty` is `compatibility` and preserved behavior is known, choose `Migration`.
+4. If `dominant_uncertainty` is `low_local` and scope stays bounded, choose `Quick Task`.
+5. If uncertainty still cannot be classified honestly, choose `Full Delivery`.
+
+## Anti-Patterns
+
+- Do not choose `Quick Task` for a dependency or framework upgrade just because the code diff looks small.
+- Do not choose `Migration` when acceptance criteria or business semantics are being redefined.
+- Do not choose `Full Delivery` for straightforward modernization work only because internal architecture must change.
+- Do not let file count or estimated duration override the dominant uncertainty rule.
+
+## Fast Examples
+
+- Upgrade React 16 to React 19 with preserved screens -> `Migration`
+- Add a new billing workflow -> `Full Delivery`
+- Fix a typo in one operator doc -> `Quick Task`
+- Replace one deprecated helper with known equivalent behavior -> `Quick Task`
+- Modernize fetching to React Query while preserving UX and rules -> `Migration`
+- Upgrade framework and redesign onboarding flow -> `Full Delivery`

package/context/core/project-config.md

@@ -0,0 +1,143 @@
+# Project Configuration & Tooling Standards
+
+This file defines the current execution reality for the repository. Agents must use documented commands when they exist and explicitly report when they do not.
+
+For the canonical workflow contract, including lane semantics, stage order, escalation policy, approvals, and artifact expectations, use `context/core/workflow.md`.
+
+## Current State
+
+- There is no repo-native build command for generated application code yet.
+- There is no repo-native lint command for generated application code yet.
+- There is no repo-native test command for generated application code yet.
+- There is no single canonical package manager or language toolchain for future applications yet.
+- OpenKit uses the mode-aware workflow documented in `context/core/workflow.md`; keep tooling and command guidance here aligned with that live contract instead of re-stating lane policy in full.
+- The active compatibility mirror uses a mode-aware schema and `.opencode/workflow-state.js` supports that workflow model.
+- The preferred operator install path is now global: `npm install -g openkit`, then `openkit run` and `openkit doctor`.
+- The checked-in repository-local runtime still exists as the authoring and compatibility surface under `.opencode/`.
+- `registry.json` and `.opencode/install-manifest.json` are additive local metadata surfaces; they do not imply destructive install or plugin-only packaging.
+- Repository-internal runtime surfaces still include workflow state, workflow-state CLI, hooks, agents, skills, commands, context, and maintained docs.
+- Global-facing metadata surface is currently limited to documentation and metadata that explain the global install and compatibility contract.
+
+## Commands That Do Exist
+
+- Session hook configuration lives in `hooks/hooks.json`.
+- The session-start hook script lives in `hooks/session-start`.
+- The global OpenKit CLI entrypoint lives at `bin/openkit.js`.
+- The OpenCode kit manifest lives in `.opencode/opencode.json`.
+- The global install writes its own profile manifest under the OpenCode home directory.
+- The active compatibility mirror lives in `.opencode/workflow-state.json`.
+- The managed work-item backing store lives in `.opencode/work-items/`.
+- The workflow-state CLI lives at `.opencode/workflow-state.js`.
+- Workflow command contracts live under `commands/`.
+- Registry metadata lives in `registry.json`.
+- Install metadata lives in `.opencode/install-manifest.json`.
+- The repository does not contain a root `opencode.json` entrypoint.
+
+### Workflow-State Utility Commands
+
+These are repository workflow commands, not application build/lint/test commands:
+
+- `npm install -g openkit`
+- `openkit install-global`
+- `openkit doctor`
+- `openkit run [args]`
+- `openkit upgrade`
+- `openkit uninstall [--remove-workspaces]`
+
+- `node .opencode/workflow-state.js status`
+- `node .opencode/workflow-state.js doctor`
+- `node .opencode/workflow-state.js version`
+- `node .opencode/workflow-state.js profiles`
+- `node .opencode/workflow-state.js show-profile <name>`
+- `node .opencode/workflow-state.js sync-install-manifest <name>`
+- `node .opencode/workflow-state.js show`
+- `node .opencode/workflow-state.js validate`
+- `node .opencode/workflow-state.js start-feature <feature_id> <feature_slug>`
+- `node .opencode/workflow-state.js start-task <mode> <feature_id> <feature_slug> <mode_reason>`
+- `node .opencode/workflow-state.js create-work-item <mode> <feature_id> <feature_slug> <mode_reason>`
+- `node .opencode/workflow-state.js list-work-items`
+- `node .opencode/workflow-state.js show-work-item <work_item_id>`
+- `node .opencode/workflow-state.js activate-work-item <work_item_id>`
+- `node .opencode/workflow-state.js advance-stage <stage>`
+- `node .opencode/workflow-state.js set-approval <gate> <status> [approved_by] [approved_at] [notes]`
+- `node .opencode/workflow-state.js set-routing-profile <work_intent> <behavior_delta> <dominant_uncertainty> <scope_shape> <selection_reason>`
+- `node .opencode/workflow-state.js link-artifact <kind> <path>`
+- `node .opencode/workflow-state.js scaffold-artifact <task_card|plan|migration_report> <slug>`
+- `node .opencode/workflow-state.js list-tasks <work_item_id>`
+- `node .opencode/workflow-state.js create-task <work_item_id> <task_id> <title> <kind> [branch] [worktree_path]`
+- `node .opencode/workflow-state.js claim-task <work_item_id> <task_id> <owner> <requested_by>`
+- `node .opencode/workflow-state.js release-task <work_item_id> <task_id> <requested_by>`
+- `node .opencode/workflow-state.js reassign-task <work_item_id> <task_id> <owner> <requested_by>`
+- `node .opencode/workflow-state.js assign-qa-owner <work_item_id> <task_id> <qa_owner> <requested_by>`
+- `node .opencode/workflow-state.js set-task-status <work_item_id> <task_id> <status>`
+- `node .opencode/workflow-state.js validate-work-item-board <work_item_id>`
+- `node .opencode/workflow-state.js record-issue <issue_id> <title> <type> <severity> <rooted_in> <recommended_owner> <evidence> <artifact_refs>`
+- `node .opencode/workflow-state.js clear-issues`
+- `node .opencode/workflow-state.js route-rework <issue_type> [repeat_failed_fix]`
+
+Current workflow-state behavior:
+
+- The CLI understands the current mode-aware workflow model.
+- `npm install -g openkit` installs the OpenKit CLI globally.
+- `openkit run` materializes the globally managed kit into the OpenCode home directory on first use when needed.
+- `openkit doctor` checks the global install and the current workspace bootstrap.
+- `openkit install-global` remains available as a manual or compatibility setup path.
+- `openkit run` launches OpenCode with the globally installed `openkit` profile and workspace-specific environment.
+- `openkit upgrade` refreshes the global managed kit bundle in place.
+- `openkit uninstall` removes the global managed kit and profile, with optional workspace cleanup.
+- `status`, `doctor`, `version`, `profiles`, `show-profile`, and `sync-install-manifest` are part of the current runtime inspection surface.
+- `start-feature` remains available as a compatibility shortcut and initializes `Full Delivery` mode.
+- `start-task` is the preferred explicit entrypoint for new mode-aware state.
+- `create-work-item`, `list-work-items`, `show-work-item`, and `activate-work-item` are the live work-item coordination commands.
+- `list-tasks`, `create-task`, `claim-task`, `release-task`, `reassign-task`, `assign-qa-owner`, `set-task-status`, and `validate-work-item-board` are the live full-delivery task-board commands.
+- `scaffold-artifact` is a narrow helper for creating and linking `task_card`, `plan`, and `migration_report` artifacts from checked-in templates.
+- `set-routing-profile` updates the explicit routing metadata used to justify and validate lane selection.
+- `task_card` scaffolding requires `quick` mode and is intentionally allowed as optional traceability in the quick lane.
+- `plan` scaffolding requires `full` mode at `full_plan` or `migration` mode at `migration_strategy`, and it always requires a linked architecture artifact.
+- `migration_report` scaffolding requires `migration` mode at `migration_baseline` or `migration_strategy` and is intended for one-file migration tracking.
+- `doctor` now checks active-work-item pointer integrity, compatibility-mirror alignment, and task-board validity when the active full-delivery stage depends on a task board.
+- Task-board support is bounded: only full-delivery work items may use it, and it does not imply unrestricted parallel safety outside the validated command surface.
+
+## Global Kit Contract
+
+- The preferred product surface is now the globally installed OpenKit kit inside the OpenCode home directory.
+- Repository-internal runtime surfaces remain `.opencode/opencode.json`, workflow-state files, the workflow-state CLI, hooks, agents, skills, commands, context, and maintained docs.
+- `registry.json` documents available components and metadata for the global-kit compatibility direction.
+- `.opencode/install-manifest.json` records which local profile is active and keeps install semantics explicit and non-destructive.
+- Global install writes its own managed kit bundle, profile manifest, and workspace state under the OpenCode home directory.
+- The checked-in repository runtime remains important for authoring, tests, and compatibility, not as the preferred end-user install shape.
+
+## Validation Reality By Mode
+
+### Quick Task
+
+- Use the closest real verification path available.
+- If no test framework exists, manual verification is acceptable when reported clearly.
+- Do not invent commands that the repository has not adopted.
+
+### Full Delivery
+
+- Prefer the strongest real validation path available.
+- If no test or build tooling exists, explicitly record that the validation path is unavailable.
+- Do not claim TDD or automated QA evidence unless the supporting commands actually exist.
+
+### Migration
+
+- Prefer baseline capture, preserved-invariant tracking, compatibility evidence, build/test/typecheck results, codemod evidence, smoke checks, and targeted regression checks over default TDD-first execution.
+- Refactor only to create seams, adapters, or compatibility boundaries that make the migration safer; do not treat migration as an excuse for a rewrite.
+- If suitable test tooling exists, add focused tests only where they clarify behavior during the migration; do not force greenfield TDD semantics onto broad upgrades by default.
+- If no repo-native validation commands exist, state the missing validation path and record manual before/after evidence honestly.
+
+## Future Update Rule
+
+When this repository adopts a real application stack, update both this file and `AGENTS.md` with the exact commands before expecting agents to run them.
+
+When the workflow-state CLI gains new mode-aware capabilities, update this file at the same time so the documented command behavior matches reality.
+
+## Execution Rules For Agents
+
+1. Use documented commands only.
+2. If a command is missing or stale, say so explicitly in the report.
+3. Do not substitute guessed commands from a preferred stack.
+4. Prefer `.opencode/workflow-state.js` over manual JSON edits when an operation is supported.
+5. Do not run destructive commands unless the user explicitly requests them.

package/context/core/session-resume.md

@@ -0,0 +1,85 @@
+# Session Resume Protocol
+
+Use this file when continuing work that may have started in a previous session.
+
+For the canonical workflow contract, including lane semantics, stage order, escalation policy, approvals, and artifact expectations, use `context/core/workflow.md`.
+
+## Required Read Order
+
+1. `AGENTS.md` for repository-wide rules and current-state guardrails
+2. `context/navigation.md` for context discovery and current-vs-future wayfinding
+3. `.opencode/workflow-state.json` as the active compatibility mirror for the current work item
+4. Determine `mode` and `current_stage`
+5. Read the mode-appropriate artifact or task context
+6. Read any related QA issues, approval notes, or escalation metadata
+
+## Mode-Aware Resume Rules
+
+### Quick Task
+
+If `mode` is `quick`:
+
+- read the quick task card if `artifacts.task_card` is present
+- if there is no task card, treat missing recorded quick context as a repair need; resume only from inspectable repository state and recorded workflow evidence, and repair the missing quick context before advancing when the current stage requires it
+- if `current_stage` is `quick_plan`, inspect the bounded checklist, acceptance confirmation, and verification path before resuming implementation
+- if `current_stage` is `quick_build`, inspect the recorded `quick_plan` content first; do not treat the absence of a task card as missing workflow
+- if `current_stage` is `quick_verify`, inspect the latest QA Lite evidence before continuing
+- if `current_stage` is `quick_done`, confirm `quick_verified` is approved and the closing evidence remains inspectable on resume
+
+Quick-lane reminder:
+
+- `quick_plan` is already part of the live contract, even when no separate doc artifact exists
+- QA Lite evidence is already part of the live contract, even when it is stored only in workflow state and session notes
+- do not invent a quick task board, extra lane, or extra artifact requirement while resuming quick work
+
+### Full Delivery
+
+If `mode` is `full`:
+
+- read the artifact referenced by the current stage when it exists
+- if `work_item_id` is present, inspect `.opencode/work-items/index.json` and the active work-item state before trusting task-aware full-delivery context
+- if the current full-delivery stage is `full_plan`, `full_implementation`, or `full_qa`, inspect the task board when it exists and confirm it belongs only to this full work item
+- restore both feature-level and task-level context: current stage owner, active work item id, ready/active task summary, and any task-specific evidence tied to the next decision
+- if `current_stage` is `full_qa`, read the current QA report and related plan first
+- preserve the approval-gate context before advancing or rerouting
+- if resuming at a handoff boundary, inspect the latest approved gate notes before starting new work
+
+### Migration
+
+If `mode` is `migration`:
+
+- read the linked architecture artifact when present because it carries the baseline and compatibility model for the upgrade
+- read the migration plan in `docs/plans/` when it exists
+- if `current_stage` is `migration_baseline`, inspect `docs/templates/migration-baseline-checklist.md` and the recorded current versions, preserved invariants, compatibility hotspots, and likely breakpoints before planning
+- if `current_stage` is `migration_strategy`, inspect the staged upgrade sequence, seam or adapter decisions, rollback notes, and validation path before resuming implementation
+- if `current_stage` is `migration_upgrade`, inspect the migration strategy and latest execution evidence before continuing
+- if `current_stage` is `migration_verify`, inspect `docs/templates/migration-verify-checklist.md` and the latest regression, smoke, compatibility, and parity evidence before deciding closure or reroute
+- if `current_stage` is `migration_done`, confirm `migration_verified` is approved and the closing evidence remains inspectable on resume
+- migration mode still has no task board in the live contract
+
+## General Resume Rules
+
+- Trust repository state over memory.
+- If `status` is `blocked`, do not continue implementation until the blocker is understood.
+- If an approval gate for the active mode is still `pending`, do not silently skip to the next stage.
+- If the referenced artifact file is missing, report the mismatch and repair the docs/state before proceeding.
+- If `escalated_from` is `quick` or `migration`, resume from the current full-delivery stage, not from the abandoned earlier stage.
+- Use `.opencode/workflow-state.js show` or `.opencode/workflow-state.js validate` when explicit state inspection helps resume work.
+- Use `node .opencode/workflow-state.js list-work-items`, `show-work-item`, `list-tasks`, or `validate-work-item-board` when full-delivery resume depends on task-aware state.
+- Inspect whether the recorded evidence is sufficient for the current stage before acting; if not, repair the handoff context first.
+- Preserve explicit validation history when resuming; do not replace prior evidence with vague restatements.
+
+Task-aware full-delivery reminder:
+
+- `.opencode/workflow-state.json` is the active compatibility mirror, not the sole managed backing file
+- do not assume every full-delivery item has parallel work; only rely on task-board state when the runtime actually recorded it
+- quick and migration modes still have no task board
+
+The current one-way escalation behavior remains unchanged in the live contract.
+
+## Status Values
+
+- `idle`: no active feature is currently being executed
+- `in_progress`: work is active in the current stage
+- `blocked`: work cannot continue without input or repair
+- `done`: the feature has completed the active workflow

package/context/core/workflow-state-schema.md

@@ -0,0 +1,224 @@
+# Workflow State Schema
+
+This file defines the canonical fields and enums exposed through `.opencode/workflow-state.json`, which now acts as the active external compatibility mirror for the active work item.
+
+For the canonical workflow contract, including lane semantics, stage order, escalation policy, approvals, and quick-lane artifact expectations, use `context/core/workflow.md`.
+
+The schema is mode-aware and uses separate stage names for `Quick Task`, `Migration`, and `Full Delivery`.
+
+Internal runtime note:
+
+- managed per-item state lives under `.opencode/work-items/<work_item_id>/state.json`
+- the active work item is mirrored into `.opencode/workflow-state.json` for compatibility with existing docs, commands, and resume flow
+- full-delivery task boards live beside the per-item state, not inside the mirrored top-level state object
+
+## Required Top-Level Fields
+
+- `feature_id`
+- `feature_slug`
+- `mode`
+- `mode_reason`
+- `routing_profile`
+- `current_stage`
+- `status`
+- `current_owner`
+- `artifacts`
+- `approvals`
+- `issues`
+- `retry_count`
+- `escalated_from`
+- `escalation_reason`
+- `updated_at`
+- `work_item_id`
+
+## `mode` Values
+
+- `quick`
+- `migration`
+- `full`
+
+Guardrail:
+
+- do not add a `quick_plus` or similar third mode without a separate explicit schema and runtime change
+- references to `Quick Task+` describe the live successor semantics of `quick`, not a new enum
+
+## `current_stage` Values
+
+### Quick Task stages
+
+- `quick_intake`: request accepted into quick mode and scoped by the Master Orchestrator
+- `quick_plan`: the Master Orchestrator is recording the bounded quick checklist, acceptance confirmation, and verification path
+- `quick_build`: Fullstack is implementing the quick task
+- `quick_verify`: the QA Agent is performing QA Lite validation for the quick task
+- `quick_done`: the quick task is complete
+
+### Migration stages
+
+- `migration_intake`: request accepted into migration mode and scoped by the Master Orchestrator
+- `migration_baseline`: Architect is recording the current baseline, preserved invariants, compatibility map, and major breakpoints
+- `migration_strategy`: Tech Lead is defining staged upgrade sequence, seam creation, rollback points, and validation approach
+- `migration_upgrade`: Fullstack is executing the migration or upgrade work
+- `migration_verify`: the QA Agent is performing regression, compatibility, and parity validation for the migration
+- `migration_done`: the migration work is complete
+
+### Full Delivery stages
+
+- `full_intake`: request received and routed into full mode
+- `full_brief`: PM is producing or revising the product brief
+- `full_spec`: BA is producing or revising the specification
+- `full_architecture`: Architect is producing or revising the design
+- `full_plan`: Tech Lead is producing or revising the implementation plan
+- `full_implementation`: Fullstack is executing approved work
+- `full_qa`: QA is validating implementation or routing findings
+- `full_done`: the feature completed the full-delivery workflow
+
+## `status` Values
+
+- `idle`
+- `in_progress`
+- `blocked`
+- `done`
+
+## `routing_profile` Shape
+
+`routing_profile` must always contain these keys:
+
+- `work_intent`
+- `behavior_delta`
+- `dominant_uncertainty`
+- `scope_shape`
+- `selection_reason`
+
+Allowed values:
+
+- `work_intent`: `maintenance`, `modernization`, `feature`
+- `behavior_delta`: `preserve`, `extend`, `redefine`
+- `dominant_uncertainty`: `low_local`, `compatibility`, `product`
+- `scope_shape`: `local`, `adjacent`, `cross_boundary`
+
+Mode expectations:
+
+- `Quick Task` must use `work_intent = maintenance`, `behavior_delta = preserve`, and `dominant_uncertainty = low_local`
+- `Migration` must use `work_intent = modernization`, `behavior_delta = preserve`, and `dominant_uncertainty = compatibility`
+- `Full Delivery` must reflect product-facing uncertainty, changed behavior, feature intent, or cross-boundary scope
+
+## Stage Ownership Map
+
+| Stage | Default Owner |
+| --- | --- |
+| `quick_intake` | `MasterOrchestrator` |
+| `quick_plan` | `MasterOrchestrator` |
+| `quick_build` | `FullstackAgent` |
+| `quick_verify` | `QAAgent` |
+| `quick_done` | `MasterOrchestrator` |
+| `migration_intake` | `MasterOrchestrator` |
+| `migration_baseline` | `ArchitectAgent` |
+| `migration_strategy` | `TechLeadAgent` |
+| `migration_upgrade` | `FullstackAgent` |
+| `migration_verify` | `QAAgent` |
+| `migration_done` | `MasterOrchestrator` |
+| `full_intake` | `MasterOrchestrator` |
+| `full_brief` | `PMAgent` |
+| `full_spec` | `BAAgent` |
+| `full_architecture` | `ArchitectAgent` |
+| `full_plan` | `TechLeadAgent` |
+| `full_implementation` | `FullstackAgent` |
+| `full_qa` | `QAAgent` |
+| `full_done` | `MasterOrchestrator` |
+
+Feature-versus-task ownership rule:
+
+- these owners are feature-stage owners
+- a full-delivery task board may also track task-level `primary_owner` and `qa_owner` assignments without changing the feature-stage owner above
+
+Approval authority map for live gates:
+
+| Gate | Approval Authority |
+| --- | --- |
+| `quick_verified` | `QAAgent` |
+| `baseline_to_strategy` | `TechLeadAgent` |
+| `strategy_to_upgrade` | `FullstackAgent` |
+| `upgrade_to_verify` | `QAAgent` |
+| `migration_verified` | `QAAgent` |
+| `pm_to_ba` | `BAAgent` |
+| `ba_to_architect` | `ArchitectAgent` |
+| `architect_to_tech_lead` | `TechLeadAgent` |
+| `tech_lead_to_fullstack` | `FullstackAgent` |
+| `fullstack_to_qa` | `QAAgent` |
+| `qa_to_done` | `MasterOrchestrator` |
+
+## Artifacts Shape
+
+`artifacts` must always contain these keys:
+
+- `task_card`
+- `brief`
+- `spec`
+- `architecture`
+- `plan`
+- `migration_report`
+- `qa_report`
+- `adr`
+
+Usage by mode:
+
+- `Quick Task` may use `task_card`, leaves `brief`, `spec`, `architecture`, `plan`, and `qa_report` as `null`, and keeps `adr` as an empty array; the required `quick_plan` stage is workflow state, not a separate artifact slot
+- `Migration` may use `architecture`, `plan`, and optional `migration_report`, leaves `task_card`, `brief`, `spec`, and `qa_report` as `null`, and keeps `adr` as optional decision records when needed
+- `Full Delivery` uses `brief`, `spec`, `architecture`, `plan`, `qa_report`, and optional `adr`, while `task_card` stays `null`
+
+Do not assume additional quick-lane artifact keys until they are explicitly added to the runtime schema and supporting code.
+
+Task-board location and scope:
+
+- quick mode has no task-board schema surface
+- full-delivery task boards are stored in `.opencode/work-items/<work_item_id>/tasks.json`
+- task-board fields are validated by runtime code and work-item-board commands rather than being embedded into `.opencode/workflow-state.json`
+
+## Approvals Shape
+
+Approval entries use the canonical shape:
+
+- `status`
+- `approved_by`
+- `approved_at`
+- `notes`
+
+Mode-specific approval keys:
+
+### Quick Task
+
+- `quick_verified`
+
+### Migration
+
+- `baseline_to_strategy`
+- `strategy_to_upgrade`
+- `upgrade_to_verify`
+- `migration_verified`
+
+### Full Delivery
+
+- `pm_to_ba`
+- `ba_to_architect`
+- `architect_to_tech_lead`
+- `tech_lead_to_fullstack`
+- `fullstack_to_qa`
+- `qa_to_done`
+
+Validation must be mode-aware. Do not require full-delivery gates for quick mode or quick gates for full mode.
+
+Approval-entry expectations:
+
+- `approved_by` should identify the live approval authority for the gate when status is `approved`
+- `notes` should record handoff readiness, notable assumptions, or rejection reasons in inspectable form
+- `quick_verified.notes` should capture QA Lite evidence or reference where that evidence is stored
+- gate notes should be sufficient for session resume without relying on unstated memory
+
+## Escalation Fields
+
+- `escalated_from`: `null`, `quick`, or `migration`
+- `escalation_reason`: `null` or a short explanation of why quick or migration work was promoted to full delivery
+
+These fields allow the repository to preserve history when a quick or migration item becomes a full-delivery item.
+
+That compatibility rule stays in place unless a later approved migration changes it deliberately.