@polymorphism-tech/morph-spec 7.4.0 → 7.6.0

package/framework/rules/morph-workflow.md

@@ -1,191 +1,192 @@
----
-stacks:
-  - "*"
----
-
-# MORPH-SPEC Workflow Rules
-
-> Always-active rules for all MORPH-SPEC managed projects.
-
----
-
-## Spec-First Mandate
-
-**NEVER skip to code without a specification.** Every feature must progress through phases:
-
-1. **Proposal** — Problem statement + acceptance criteria (`0-proposal/proposal.md`)
-2. **Design** (optional, UI-heavy) — Design system + mockups + flows (`1-design/`)
-3. **Plan** — Technical spec + mandate + tasks (`2-plan/spec.md`, `mandate.md`, `tasks.json`)
-4. **Implement** — Code + recap (`3-implement/recap.md`)
-5. **Review** — Review report + Gate 3 (`4-review/review-report.md`)
-
----
-
-## Phase Sequence
-
-```
-proposal → [design] → plan → implement → review
-```
-
-Use `morph-spec status {feature}` to see current phase and pending approval gates.
-
----
-
-## Phase Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/morph-proposal {feature}` | Full spec pipeline (phases 1-4, pauses for approval) |
-| `/morph-apply {feature}` | Implement feature (phase 5) |
-| `/morph-status` | Feature dashboard |
-
----
-
-## State & Outputs
-
-| Path | Notes |
-|------|-------|
-| `.morph/state.json` | **READ-ONLY** — use `morph-spec` CLI to update |
-| `.morph/features/{feature}/{phase}/` | Feature outputs organized by phase |
-| `.morph/framework/` | **READ-ONLY** — framework files managed by morph-spec |
-| `.morph/config/config.json` | Project configuration (editable) |
-
-### output types
-
-Output types are defined in `src/core/paths/output-schema.js`. State sync is
-handled automatically by the `state-sync.js` PostToolUse hook — the agent
-does not need to call mark-output explicitly.
-
----
-
-## Output Paths
-
-All outputs go in `.morph/features/{feature}/`:
-
-| Phase | Path |
-|-------|------|
-| Proposal | `0-proposal/proposal.md`, `stack-scan.md`, `migration-plan.md` (optional) |
-| Design (optional) | `1-design/design-system.md`, `mockups.md`, `components.md`, `flows.md` |
-| Plan | `2-plan/spec.md`, `mandate.md`, `tasks.json`, `decisions.md` |
-| Implement | `3-implement/recap.md` + source code |
-| Review | `4-review/review-report.md` |
-
----
-
-## Checkpoints
-
-Run a checkpoint every 3 completed tasks:
-- Validate architecture compliance
-- Check package versions
-- Scan for security issues
-- Verify design system adherence (UI features)
-
----
-
-## Approval Gates
-
-Before completing any phase, verify pending approval gates:
-- `morph-spec approval-status <feature>` — check which gates are pending
-- `morph-spec approve <feature> <gate>` — approve a gate (design, plan, tasks, uiux)
-- Gates must be approved before advancing to the next phase
-
----
-
-## Protected Files
-
-**NEVER directly edit:**
-- `.morph/state.json` — Managed by CLI only
-- `.morph/framework/**` — Read-only framework content
-
----
-
-## Test File Policy
-
-When a test fails, always follow this order:
-
-1. **Analyze first** — determine if the IMPLEMENTATION is wrong or the TEST SPEC is wrong
-2. **Fix implementation first** — the test is the spec; trust it by default
-3. **Only modify a test file if the test expectation itself is incorrect** — wrong expected value, wrong behavior modeled
-4. **Before modifying any test file, explain WHY the test spec is wrong** — what the correct behavior is and why the test doesn't model it
-
-Do not modify test files to make a failing test pass when the implementation is the actual problem.
-
----
-
-## Context Maintenance
-
-After making structural changes (new packages, dependencies, project config changes), update the project context:
-- Edit `.morph/context/README.md` — update Tech Stack, Architecture, Key Integrations sections
-- Update `.morph/config/config.json` — update stack, architecture, integrations, paths
-- Structural changes include: package.json, .csproj, next.config.*, tsconfig.json, docker-compose.yml
-
----
-
-## Spec-Driven Task Execution (implement phase)
-
-BEFORE implementing ANY task during the implement phase:
-
-1. **Read tasks.json** → identify the current task object (`id`, `description`, `doneCriteria`, `dependencies`)
-2. **Read spec.md** → the FR sections that the task `description` references
-3. **Read the contracts** → the DTOs/interfaces are defined inside `spec.md` (v5 keeps contracts in the spec, not separate files)
-4. Only then begin implementation
-
-This is **NON-NEGOTIABLE**. The spec is the source of truth. Code that doesn't match the spec is a bug.
-
-Every task in `tasks.json` MUST reference its FR(s) in the `description` field so the link to the spec is explicit:
-```json
-{
-  "id": "T1",
-  "title": "Create user endpoint",
-  "description": "Implement user CRUD (FR001) and input validation (FR003). Contracts: CreateUserRequest, CreateUserResponse, UserErrors.",
-  "dependencies": [],
-  "effort": "M",
-  "doneCriteria": "POST /users creates a user and rejects invalid input",
-  "status": "pending",
-  "outputs": ["Features/UserFeature/Create/Handler.cs", "Validator.cs", "Endpoint.cs"],
-  "group": "backend"
-}
-```
-
----
-
-## Mandatory Skills per Phase
-
-During implementation, these skills MUST be invoked at the specified triggers:
-
-### Implement Phase
-| Trigger | Skill | When |
-|---------|-------|------|
-| Before each task | `superpowers:test-driven-development` | Invoke BEFORE writing any code for a task |
-| Before task done | `morph-verification-before-completion` | Invoke BEFORE running `morph-spec task done` |
-| On bug/unexpected | `superpowers:systematic-debugging` | Invoke IF a bug or unexpected behavior is encountered |
-| After all tasks | `morph-post-implementation` | Invoke AFTER all tasks completed |
-| Before PR | `morph-checklist` | Invoke BEFORE creating pull request |
-
-### Tasks Phase
-| Trigger | Skill | When |
-|---------|-------|------|
-| On parallel tasks | `superpowers:dispatching-parallel-agents` | When parallel task groups are identified |
-| Before completion | `morph-verification-before-completion` | Before completing the tasks phase |
-
-These are MANDATORY. Use the `Skill()` tool. Do NOT skip.
-
----
-
-## Scope Escalation
-
-If during implementation a task reveals significantly more complexity than estimated:
-- **Low impact:** `morph-spec task expand <feature> <task-id> --into "T00Xa: Sub" "T00Xb: Sub"`
-- **Medium/High impact:** `/morph-scope-escalation <feature>`
-- **Never** implement extra functionality within a task without registering it as a subtask
-
----
-
-## Context Window Tip
-
-When using 3+ MCPs, add `"experimental": { "mcpCliMode": true }` to `.claude/settings.json`.
-MCP tools load on-demand instead of all at startup — keeps context clean for actual work.
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+---
+stacks:
+  - "*"
+---
+
+# MORPH-SPEC Workflow Rules
+
+> Always-active rules for all MORPH-SPEC managed projects.
+
+---
+
+## Spec-First Mandate
+
+**NEVER skip to code without a specification.** Every feature must progress through phases:
+
+1. **Proposal** — Problem statement + acceptance criteria (`0-proposal/proposal.md`)
+2. **Design** (optional, UI-heavy) — Design system + mockups + flows (`1-design/`)
+3. **Plan** — Technical spec + mandate + tasks (`2-plan/spec.md`, `mandate.md`, `tasks.json`)
+4. **Implement** — Code + recap (`3-implement/recap.md`)
+5. **Review** — Review report + Gate 3 (`4-review/review-report.md`)
+
+---
+
+## Phase Sequence
+
+```
+proposal → [design] → plan → implement → review
+```
+
+Use `morph-spec status {feature}` to see current phase and pending approval gates.
+
+---
+
+## Phase Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/morph-proposal {feature}` | Full spec pipeline (phases 1-4, pauses for approval) |
+| `/morph-apply {feature}` | Implement feature (phase 5) |
+| `/morph-status` | Feature dashboard |
+
+---
+
+## State & Outputs
+
+| Path | Notes |
+|------|-------|
+| `.morph/state.json` | **READ-ONLY** — updated automatically by the `state-sync` hook |
+| `.morph/features/{feature}/{phase}/` | Feature outputs organized by phase |
+| `.morph/framework/` | **READ-ONLY** — framework files managed by morph-spec |
+| `.morph/config/config.json` | Project configuration (editable) |
+
+### output types
+
+Output types are defined in `src/core/paths/output-schema.js`. State sync is
+handled automatically by the `state-sync.js` PostToolUse hook — the agent
+does not need to record outputs through any CLI call.
+
+---
+
+## Output Paths
+
+All outputs go in `.morph/features/{feature}/`:
+
+| Phase | Path |
+|-------|------|
+| Proposal | `0-proposal/proposal.md`, `stack-scan.md`, `migration-plan.md` (optional) |
+| Design (optional) | `1-design/design-system.md`, `mockups.md`, `components.md`, `flows.md` |
+| Plan | `2-plan/spec.md`, `mandate.md`, `tasks.json`, `decisions.md` |
+| Implement | `3-implement/recap.md` + source code |
+| Review | `4-review/review-report.md` |
+
+---
+
+## Checkpoints
+
+Run a checkpoint every 3 completed tasks:
+- Validate architecture compliance
+- Check package versions
+- Scan for security issues
+- Verify design system adherence (UI features)
+
+---
+
+## Approval Gates
+
+Before completing any phase, verify pending approval gates:
+- `morph-spec approval-status <feature>` — check which gates are pending
+- `morph-spec approve <feature> <gate>` — approve a gate (`proposal`, `plan`, `review`; `uiux` if applicable)
+- `morph-spec advance <feature>` — approve the current gate AND scaffold the next phase folder in one step
+- Gates must be approved before advancing to the next phase
+
+---
+
+## Protected Files
+
+**NEVER directly edit:**
+- `.morph/state.json` — Managed by CLI only
+- `.morph/framework/**` — Read-only framework content
+
+---
+
+## Test File Policy
+
+When a test fails, always follow this order:
+
+1. **Analyze first** — determine if the IMPLEMENTATION is wrong or the TEST SPEC is wrong
+2. **Fix implementation first** — the test is the spec; trust it by default
+3. **Only modify a test file if the test expectation itself is incorrect** — wrong expected value, wrong behavior modeled
+4. **Before modifying any test file, explain WHY the test spec is wrong** — what the correct behavior is and why the test doesn't model it
+
+Do not modify test files to make a failing test pass when the implementation is the actual problem.
+
+---
+
+## Context Maintenance
+
+After making structural changes (new packages, dependencies, project config changes), update the project context:
+- Edit `.morph/context/README.md` — update Tech Stack, Architecture, Key Integrations sections
+- Update `.morph/config/config.json` — update stack, architecture, integrations, paths
+- Structural changes include: package.json, .csproj, next.config.*, tsconfig.json, docker-compose.yml
+
+---
+
+## Spec-Driven Task Execution (implement phase)
+
+BEFORE implementing ANY task during the implement phase:
+
+1. **Read tasks.json** → identify the current task object (`id`, `description`, `doneCriteria`, `dependencies`)
+2. **Read spec.md** → the FR sections that the task `description` references
+3. **Read the contracts** → the DTOs/interfaces are defined inside `spec.md` (v5 keeps contracts in the spec, not separate files)
+4. Only then begin implementation
+
+This is **NON-NEGOTIABLE**. The spec is the source of truth. Code that doesn't match the spec is a bug.
+
+Every task in `tasks.json` MUST reference its FR(s) in the `description` field so the link to the spec is explicit:
+```json
+{
+  "id": "T1",
+  "title": "Create user endpoint",
+  "description": "Implement user CRUD (FR001) and input validation (FR003). Contracts: CreateUserRequest, CreateUserResponse, UserErrors.",
+  "dependencies": [],
+  "effort": "M",
+  "doneCriteria": "POST /users creates a user and rejects invalid input",
+  "status": "pending",
+  "outputs": ["Features/UserFeature/Create/Handler.cs", "Validator.cs", "Endpoint.cs"],
+  "group": "backend"
+}
+```
+
+---
+
+## Mandatory Skills per Phase
+
+During implementation, these skills MUST be invoked at the specified triggers:
+
+### Implement Phase
+| Trigger | Skill | When |
+|---------|-------|------|
+| Before each task | `superpowers:test-driven-development` | Invoke BEFORE writing any code for a task |
+| Before marking a task complete | `morph-verification-before-completion` | Invoke BEFORE setting a task's `status` to `completed` in `tasks.json` |
+| On bug/unexpected | `superpowers:systematic-debugging` | Invoke IF a bug or unexpected behavior is encountered |
+| After all tasks | `morph-post-implementation` | Invoke AFTER all tasks completed |
+| Before PR | `morph-checklist` | Invoke BEFORE creating pull request |
+
+### Tasks Phase
+| Trigger | Skill | When |
+|---------|-------|------|
+| On parallel tasks | `superpowers:dispatching-parallel-agents` | When parallel task groups are identified |
+| Before completion | `morph-verification-before-completion` | Before completing the tasks phase |
+
+These are MANDATORY. Use the `Skill()` tool. Do NOT skip.
+
+---
+
+## Scope Escalation
+
+If during implementation a task reveals significantly more complexity than estimated:
+- **Low impact:** record the added scope in the task's `notes` field (in `tasks.json`) and track the sub-steps with native `TaskCreate`/`TaskUpdate` for the current session
+- **Medium/High impact:** `/morph-scope-escalation <feature>` — re-opens the plan so the frozen contract (`title`/`description`/`dependencies`/`doneCriteria`) can be amended through the gate
+- **Never** implement extra functionality within a task without registering it — in `notes` for small additions, or via scope escalation for anything that changes the plan contract
+
+---
+
+## Context Window Tip
+
+When using 3+ MCPs, add `"experimental": { "mcpCliMode": true }` to `.claude/settings.json`.
+MCP tools load on-demand instead of all at startup — keeps context clean for actual work.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*