@polymorphism-tech/morph-spec 7.3.0 → 7.5.0

package/framework/rules/morph-task-tracking.md

@@ -1,49 +1,69 @@
----
-stacks:
-  - "*"
----
-
-# MORPH-SPEC Task Tracking
-
-> Session tasks are MANDATORY in every MORPH-SPEC phase. They track real progress and must be
-> created BEFORE any phase work begins.
-
-## Rules
-
-1. **Every phase skill MUST create session tasks** using `TaskCreate` before reading files or generating outputs
-2. **Tasks are dynamic** — analyze the phase workflow and create tasks that reflect YOUR actual planned actions for this session
-3. **Every task MUST be updated**: `in_progress` before starting, `completed` after finishing
-4. **Pipeline orchestrators** (`/morph-proposal`, `/morph-apply`) MUST create master tasks for each phase
-5. **Never skip task creation** — even if resuming mid-phase, create tasks for remaining steps
-6. **Granularity**: minimum 2, typically 3-7 tasks per phase — adjust to complexity
-7. **For iterative work** (clarification rounds, quality loops): update task `subject` with round/score progress
-
-## Task Update Pattern
-
-```
-TaskUpdate(taskId, status="in_progress")   // before starting the step
-// ... do the work ...
-TaskUpdate(taskId, status="completed")     // after step finishes
-```
-
-For iterative tasks:
-```
-TaskUpdate(taskId, subject="Round 3 — score 82/100")
-```
-
-## Deviation Tracking
-
-When completing a task differently than originally planned, record the reason:
-
-```
-morph-spec task done <feature> <taskId> --note "Reason for deviation"
-```
-
-For after-the-fact annotation (supports multiple types):
-```
-morph-spec task annotate <feature> <taskId> "Reason" --type deviation
-morph-spec task annotate <feature> <taskId> "Context info" --type context
-morph-spec task annotate <feature> <taskId> "Resolved" --type blocker-resolved
-```
-
-Note types: `deviation` (default), `context`, `blocker-resolved`
+---
+stacks:
+  - "*"
+---
+
+# MORPH-SPEC Task Tracking
+
+> Session tasks are MANDATORY in every MORPH-SPEC phase. They track real progress and must be
+> created BEFORE any phase work begins.
+
+## Rules
+
+1. **Every phase skill MUST create session tasks** using `TaskCreate` before reading files or generating outputs
+2. **Tasks are dynamic** — analyze the phase workflow and create tasks that reflect YOUR actual planned actions for this session
+3. **Every task MUST be updated**: `in_progress` before starting, `completed` after finishing
+4. **Pipeline orchestrators** (`/morph-proposal`, `/morph-apply`) MUST create master tasks for each phase
+5. **Never skip task creation** — even if resuming mid-phase, create tasks for remaining steps
+6. **Granularity**: minimum 2, typically 3-7 tasks per phase — adjust to complexity
+7. **For iterative work** (clarification rounds, quality loops): update task `subject` with round/score progress
+
+## Task Update Pattern
+
+```
+TaskUpdate(taskId, status="in_progress")   // before starting the step
+// ... do the work ...
+TaskUpdate(taskId, status="completed")     // after step finishes
+```
+
+For iterative tasks:
+```
+TaskUpdate(taskId, subject="Round 3 — score 82/100")
+```
+
+## Persisting Progress to `tasks.json`
+
+Native session tasks (`TaskCreate`/`TaskUpdate`) track your live work. To persist
+task progress for the feature, write `.morph/features/{feature}/2-plan/tasks.json`,
+touching ONLY the mutable fields:
+
+- `status` — `pending` → `in_progress` → `completed`
+- `outputs` — the files the task produced
+- `notes` — free-text record (deviations, context, resolved blockers)
+
+The plan contract — `title`, `description`, `dependencies`, `effort`, `doneCriteria`,
+`group` — is frozen after Gate 2. Any attempt to change it is blocked by the
+`protect-spec-files` hook.
+
+Use the `Write` tool (whole-file rewrite) OR the `Edit` tool — `Edit` is allowed
+as long as it touches only `status`, `outputs`, and `notes`. State is then synced
+automatically by the `state-sync` PostToolUse hook; you do not call a CLI to mark
+output.
+
+## Deviation Tracking
+
+When completing a task differently than originally planned, record the reason in the
+task's `notes` field. Use the `notes` array to capture deviations, added context, or
+resolved blockers — for example:
+
+```json
+{
+  "id": "T3",
+  "status": "completed",
+  "outputs": ["Features/User/Update/Handler.cs"],
+  "notes": [
+    "deviation: split validation into a separate validator for testability",
+    "blocker-resolved: EF migration conflict fixed by regenerating the snapshot"
+  ]
+}
+```

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*

package/framework/skills/README.md

@@ -16,7 +16,7 @@ These are the only skills the harness needs. MORPH.md references them by path.
 | `morph-stack-scan`    | Detect stack drift in existing projects, generate migration-plan.md  | yes            |
 | `morph-plan`          | Produce spec.md + mandate.md + tasks.json (Gate 2)                   | yes            |
 | `morph-implement`     | Execute each task with standard + persona, auto-advance between tasks| no             |
-| `morph-eval`          | Score work 0-10 across 4 dimensions, silence on score >= 8           | no             |
+| `morph-eval`          | Score work 0-10 across 4 dimensions, silence on score >= 9           | no             |
 | `morph-review`        | Final review report with scores + recommendation (Gate 3)            | yes            |
 | `morph-standards`     | Locate and load a specific standard on demand                        | no             |