@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/README.md

@@ -3,14 +3,14 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 8.47.0  
+**Version:** 9.1.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
 
 ## What it does
 
-morph-spec enforces a spec-first development workflow. When you ask for a feature, it does not write code immediately. It runs through structured phases (proposal, plan, implement) with approval gates before a single line of implementation is generated. Each phase produces traceable output files. Every decision is documented.
+morph-spec enforces a spec-first development workflow. When you ask for a feature, it does not write code immediately. It runs through structured phases (plan, implement, review) with approval gates before a single line of implementation is generated. Each phase produces traceable output files. Every decision is documented.
 
 It integrates natively with Claude Code: skills become slash commands, agents become native subagents, hooks inject state context automatically, and rules enforce standards based on file paths.
 
@@ -61,17 +61,17 @@ your-project/
 │   ├── config/
 │   │   └── config.json              # Project configuration
 │   ├── framework/
-│   │   ├── agents.json              # 8 domain personas (READ-ONLY)
+│   │   ├── agents.json              # 10 personas (READ-ONLY)
 │   │   ├── standards/               # Coding and architecture standards (READ-ONLY)
 │   │   └── templates/               # Code and IaC templates (READ-ONLY)
 │   ├── context/                     # Project context (README.md, standards.md)
 │   ├── features/                    # Active features
 │   │   └── {feature}/
-│   │       ├── 0-proposal/          # Problem statement + acceptance criteria
-│   │       ├── 1-design/            # UI/UX design (optional, UI-heavy features)
-│   │       ├── 2-plan/              # usecases/ + spec.md + tasks.json
-│   │       ├── 3-implement/         # Recap and implementation notes
-│   │       └── 4-review/            # Review report + Gate 3
+│   │       ├── feature.json         # Authoritative state (committed)
+│   │       ├── 2-plan/              # plan.md + checks.json (from plan-check)
+│   │       ├── 1-design/            # UI/UX design (optional, after the plan gate)
+│   │       ├── 3-implement/         # reports/F{n}.md — one per plan slice
+│   │       └── 4-review/            # verifier.md + reviewer.md [+ security.md]
 │   └── state.json                   # READ-ONLY — managed by CLI only
 └── .claude/
     ├── commands/                    # Slash commands
@@ -88,28 +88,27 @@ your-project/
 Features move through structured phases. Some are optional depending on feature type.
 
 ```
-proposal → [uiux] → plan → implement → review
+plan → [uiux] → implement → review
 ```
 
-`uiux` is optional — applies only to UI-heavy features.
+`uiux` is optional — it applies only to UI-heavy features and comes after the plan gate.
 
 ### Phase outputs
 
 
 | Phase     | Directory       | Key files                                                          |
 | --------- | --------------- | ------------------------------------------------------------------ |
-| Proposal  | `0-proposal/`   | `proposal.md`, `stack-scan.md`, `migration-plan.md` (optional)     |
+| Plan      | `2-plan/`       | `plan.md` (scenarios `C{n}`, decisions, slices `F{n}`), `checks.json`, `stack-scan.md`, `scout-map.md` |
 | Design    | `1-design/`     | `design-system.md`, `mockups.md`, `components.md`, `flows.md`      |
-| Plan      | `2-plan/`       | `usecases/`, `spec.md`, `tasks.json`, `decisions.md`               |
-| Implement | `3-implement/`  | `recap.md` + source code                                           |
-| Review    | `4-review/`     | `review-report.md`                                                 |
+| Implement | `3-implement/`  | `reports/F{n}.md` + source code                                    |
+| Review    | `4-review/`     | `verifier.md`, `reviewer.md`, `security.md` (when required)        |
 
 
 ### Approval gates
 
-- **Gate 1 (Proposal)** — Problem statement must be approved before plan.
-- **Gate 2 (Plan)** — Use cases + spec + tasks must be approved before implement.
-- **Gate 3 (Review)** — Review report must be approved before archive.
+- **Plan gate** — `plan.md` must pass `morph-spec plan-check` with zero errors (it writes `checks.json`) before implement.
+- **UI/UX gate** (optional) — the `1-design/` outputs, after the plan gate.
+- **Gate 3 (Review)** — independent sub-agents write `verifier.md` (every `C{n}` proved), `reviewer.md` and, when required, `security.md`, each answering SHIP or FIX.
 
 In `trust: "auto"` mode (default), gates auto-pass without risk signals. See `framework/MORPH.md` for risk-signal details.
 
@@ -123,9 +122,9 @@ morph-spec approval-status {feature}
 
 ## Work-type routing & worktrees
 
-Not every change deserves the full pipeline. Every feature is born with a **work type** — `feature`, `bug`, `chore`, or `hotfix` — set via `morph-spec create {feature} --type <type>` or classified from free text with `--request "<text>"`. The type dimensions the pipeline: `feature` runs the full proposal → [uiux] → plan → implement → review sequence; `bug` runs a lean proposal/plan; `chore` skips straight to implement (Gates 1/2 stamped by policy at birth); `hotfix` runs scout (read-only root-cause) → surgical fix → test loop, and its Gate 3 always pauses for a human even under `trust: auto`. Change the type mid-flight with `morph-spec retype {feature} {newType}` (undoes only policy-stamped gates, preserves human approvals, blocked after Gate 3).
+Not every change deserves the full pipeline. Every feature is born with a **work type** — `feature`, `bug`, `chore`, or `hotfix` — set via `morph-spec create {feature} --type <type>` or classified from free text with `--request "<text>"`. The type dimensions the pipeline: `feature` and `bug` run the full plan → [uiux] → implement → review sequence; `chore` skips straight to implement (plan gate stamped by policy at birth); `hotfix` runs scout (read-only root-cause) → surgical fix → test loop, and its Gate 3 always pauses for a human even under `trust: auto`. Change the type mid-flight with `morph-spec retype {feature} {newType}` (undoes only policy-stamped gates, preserves human approvals, blocked after Gate 3).
 
-Independent features can also be developed **in parallel, each isolated in its own git worktree** — one feature, one worktree, one Claude Code instance. `morph-spec create {feature} --worktree` (or `morph-spec worktree setup {feature}`) creates `worktrees/{feature}/` on branch `morph/{feature}`. The authoritative `feature.json` travels committed on the branch; shared infra (`node_modules`, `.claude`, `.morph/framework`) is linked via junctions (`morph-spec worktree link --all` repairs it if missing). Close out with `morph-spec worktree finish {feature}` (merges `--no-ff` back into the clean primary root) followed by `morph-spec archive {feature}` at the root; `morph-spec worktree list` shows every active worktree with its phase and gate status.
+Independent features can also be developed **in parallel, each isolated in its own git worktree** — one feature, one worktree, one Claude Code instance. `morph-spec create {feature} --worktree` (or `morph-spec worktree setup {feature}`) creates `worktrees/{feature}/` on branch `morph/{feature}`. The authoritative `feature.json` travels committed on the branch; shared infra (`node_modules`, `.claude`, `.morph/framework`) is linked via junctions (`morph-spec worktree link --all` repairs it if missing). Close out with `morph-spec finish {feature} --pr|--merge` (archive + integrate + teardown); `morph-spec worktree list` shows every active worktree with its phase and gate status.
 
 ---
 
@@ -136,7 +135,7 @@ These commands are available inside Claude Code after init.
 
 | Command                       | Description                                             |
 | ------------------------------ | ---------------------------------------------------------- |
-| `/morph-proposal {feature}`    | Business understanding + plan (Gates 1 and 2)                |
+| `/morph-plan {feature}`        | Interview, `plan.md`, `plan-check` and the plan gate         |
 | `/morph-apply {feature}`       | Autonomous execution + review (Gate 3)                        |
 | `/morph-hotfix {feature}`      | Surgical hotfix ADW — scout → fix → human Gate 3 → ship         |
 | `/morph-status [feature]`      | Status of the active (or specified) feature                      |
@@ -164,7 +163,7 @@ morph-spec doctor --full               # Full health check (all file verificatio
 ```bash
 morph-spec fleet                              # Every active feature (root + worktrees): phase, gates, activity
 morph-spec status {feature}                    # Feature status dashboard
-morph-spec approve {feature} {gate}            # Approve a phase gate (proposal, plan, review)
+morph-spec approve {feature} {gate}            # Approve a phase gate (plan, uiux, review)
 morph-spec advance {feature}                   # Approve the current gate and scaffold the next phase folder
 morph-spec approval-status {feature}           # Show approval status for all gates
 morph-spec finish {feature} --pr|--merge       # Close a feature: archive + integrate (PR or local merge) + teardown
@@ -173,7 +172,7 @@ morph-spec archive {feature}                   # Archive WITHOUT integrating (le
 
 `finish` is the normal close for both flows: it archives (committing the move inside `morph/{feature}`), then integrates — `--merge` merges `--no-ff` into the default branch locally; `--pr` pushes the branch and runs `gh pr create` (needs `origin` + authenticated `gh`) — and tears down the worktree if there is one. Plain `archive` is reserved for legacy features (born before every feature had a `morph/{feature}` branch) and cleanup.
 
-Task progress within a feature is recorded in `tasks.json` — Claude writes the mutable `status`/`outputs`/`notes` fields as it goes, and there is no separate CLI command for starting or finishing a task.
+Progress within a feature is the slice reports `3-implement/reports/F{n}.md`: absent means pending, `PARCIAL` on the first line means partial. There is no CLI command for starting or finishing a slice.
 
 ### Validation
 
@@ -181,7 +180,7 @@ Task progress within a feature is recorded in `tasks.json` — Claude writes the
 morph-spec validate                    # Run all validators
 morph-spec validate {validator}        # Run specific validator
 morph-spec validate-feature {feature}  # Content-aware feature validation
-morph-spec verify {feature} [task]     # Deterministic build+tests+validators chain, before the LLM judge
+morph-spec verify {feature}            # Deterministic build+tests+validators chain, before the LLM judge
 ```
 
 ### Work-type routing
@@ -190,7 +189,6 @@ morph-spec verify {feature} [task]     # Deterministic build+tests+validators ch
 morph-spec create {feature} --type feature|bug|chore|hotfix --description "<what/why>"   # Explicit birth: type dimensions the pipeline, description is required
 morph-spec create {feature} --request "<free text>"           # Detector classifies the type AND seeds the description
 morph-spec retype {feature} {newType}                          # Change work type mid-flight (blocked after Gate 3)
-morph-spec dag {feature} [--mermaid]                            # DAG dispatch decision; --mermaid emits a flowchart
 ```
 
 ### Worktrees (parallel development)
@@ -200,7 +198,7 @@ morph-spec create {feature} --description "<what/why>" --worktree   # Birth the
 morph-spec worktree setup {feature}      # Create worktrees/{feature}/ on branch morph/{feature}
 morph-spec worktree link [--all]         # Relink shared infra (node_modules, .claude, .morph/framework)
 morph-spec worktree list [--json]        # List active feature worktrees with phase/gate status
-# Close a worktree feature with `morph-spec finish {feature} --pr|--merge` (see Feature workflow) — it absorbed `worktree finish`.
+# Close a worktree feature with `morph-spec finish {feature} --pr|--merge` (see Feature workflow).
 ```
 
 **Codebase graph** — optional, fail-open. `init` installs [graphify](https://pypi.org/project/graphifyy/) (pinned 0.9.50) when a Python toolchain is available and writes a stack-aware `.graphifyignore`; without one, it records the fact and moves on. Everything degrades to grep.
@@ -218,7 +216,7 @@ The gain is **precision, not recall**: the graph finds nothing grep would miss,
 
 ## Agent model
 
-morph-spec dispatches 8 flat domain personas — no tiers, no hierarchy — defined in `.morph/framework/agents.json` (single source of truth) and installed identically to `.claude/agents/morph-{id}.md`. Claude picks the right persona per task from the domains/keywords in `agents.json`, then dispatches it via the `Agent` tool.
+morph-spec dispatches 10 flat personas — no tiers, no hierarchy — defined in `.morph/framework/agents.json` (single source of truth) and installed identically to `.claude/agents/morph-{id}.md`. Claude picks the right persona per plan slice from the domains/keywords in `agents.json`, then dispatches it via the `Agent` tool.
 
 | Persona          | Domain                                | Model  |
 | ---------------- | -------------------------------------- | ------ |
@@ -228,7 +226,9 @@ morph-spec dispatches 8 flat domain personas — no tiers, no hierarchy — defi
 | `nextjs-expert`   | Frontend (Next.js/React)                | sonnet |
 | `ui-designer`     | UI/UX, design systems                    | sonnet |
 | `infra-engineer`  | Jobs, deployment, observability          | sonnet |
-| `evaluator`       | Independent code/architecture review (Gate 3) | opus |
+| `verifier`        | Gate 3: proves every scenario `C{n}` (read-only) | sonnet (opus for prompt/model or media) |
+| `reviewer`        | Gate 3: judges the diff (read-only)      | sonnet |
+| `security`        | Gate 3: security review (read-only)      | opus   |
 | `scout`           | Read-only codebase diagnosis             | sonnet |
 
 `morph-spec doctor` detects drift between `agents.json` and the generated `.claude/agents/morph-*.md` files — never hand-edit the generated files.
@@ -237,16 +237,18 @@ morph-spec dispatches 8 flat domain personas — no tiers, no hierarchy — defi
 
 ## Hooks
 
-Guardrail hooks are installed into `.claude/settings.local.json` across 7 event bindings. All are **fail-open** — they check that state exists first and silently no-op on missing/corrupt state; they never throw, write state, or orchestrate.
+Guardrail hooks are installed into `.claude/settings.local.json` across 13 event bindings. All are **fail-open** — they check that state exists first and silently no-op on missing/corrupt state; they never throw, write state, or orchestrate.
 
 
 | Event                      | Hook(s)                                                              | Purpose                                                                     |
 | --------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
 | `SessionStart`              | `worktree-context.js`                                                   | Injects feature identity (worktree) or active-feature summary (root)           |
-| `PreToolUse` (Write\|Edit)  | `protect-spec-files.js`, `enforce-phase-writes.js`                       | Blocks edits to the frozen plan contract post-Gate-2; enforces phase folders    |
-| `PreToolUse` (Bash)         | `pre-bash-denylist.js`                                                   | Detects destructive shell patterns                                              |
-| `PostToolUse`               | `tasks-json-guard.js`, `trace-autogen.js`, `comment-guard.js` | Guards `tasks.json` plan-contract edits; auto-generates execution traces; blocks added comments the comment standard forbids |
-| `PostToolUse`               | `state-sync.js`, `gate-guard.js`, `loop-detect.js`                        | Syncs feature state; enforces gate ordering; detects repeated-action loops       |
+| `PreToolUse` (Write\|Edit)  | `protect-spec-files.js`, `enforce-phase-writes.js`                       | Freezes `plan.md` after the plan gate (only `plan-check` writes `checks.json`); enforces phase folders |
+| `PreToolUse` (Bash)         | `pre-bash-denylist.js`, `block-destructive-worktree-removal.js`, `block-raw-worktree-add.js`, `warn-bash-source-write.js`, `heavy-gate.js`, `worktree-env-inject.js` | Destructive-command guards, worktree governance, heavy-node semaphore, per-worktree env |
+| `WorktreeCreate` / `WorktreeRemove` | `worktree-create.js`, `worktree-remove.js`                     | Native worktrees delegate to the CLI                                            |
+| `PostToolUse` (Write\|Edit) | `comment-guard.js`                                                       | Blocks added comments the comment standard forbids                              |
+| `PostToolUse`               | `state-sync.js`, `gate-guard.js`                                         | Syncs feature state; enforces gate ordering                                     |
+| `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `SubagentStop`, `UserPromptSubmit` | `telemetry-log.js`, `loop-detect.js`, `graph-refresh-kick.js`, `heavy-release.js` | Telemetry, repeated-action loops, graph refresh, heavy-slot release |
 | `Stop`                      | `validate-completion.js`                                                  | Warns about incomplete tasks, missing outputs, or pending approval gates         |
 
 
@@ -259,11 +261,10 @@ Protected files (via `permissions.deny`):
 
 ## Rules
 
-Rules are installed to `.claude/rules/` based on your detected stack (`stacks:` frontmatter, same tagging mechanism as agents and templates) and activate automatically based on file path patterns (`paths:` frontmatter). A subset of the current set:
+Rules are installed to `.claude/rules/` based on your detected stack (`stacks:` frontmatter, same tagging mechanism as agents and templates) and activate automatically based on file path patterns (`paths:` frontmatter); no rule is always active — the workflow lives in `MORPH.md` and the skills. A subset of the current set:
 
 | Rule file                     | Applies to                                     | Stack     |
 | ----------------------------- | ------------------------------------------------- | --------- |
-| `morph-workflow.md`           | Always active — spec-first workflow                | any       |
 | `csharp-standards.md`         | `**/*.cs`, `**/*.csproj`                            | dotnet    |
 | `frontend-standards.md`       | `**/*.tsx`, `**/*.css`, `**/*.scss`                 | nextjs    |
 | `nextjs-standards.md`         | Next.js-specific patterns                           | nextjs    |
@@ -304,16 +305,16 @@ After updating, run `morph-spec doctor` to confirm the installation is healthy.
 
 ## Key rules
 
-**Never skip phases.** Every feature starts with a proposal. No code is written until the design is approved and a task list exists.
+**Never skip phases.** Every feature starts with a plan. No code is written until `plan.md` passes `plan-check` and the plan gate is approved.
 
 **Never edit protected files directly:**
 
 - `.morph/state.json` — derived automatically from `feature.json`; use `morph-spec approve`/`advance`/`gate-decision` to change feature state
 - `.morph/framework/` — read-only, updated by `morph-spec update`
 
-**Always document decisions.** Each feature can have a `2-plan/decisions.md`. Architectural choices go there, not in commit messages.
+**Always document decisions.** Architectural choices go in the `## Decisões` section of `2-plan/plan.md` (ADRs are indexed when the feature closes), not in commit messages.
 
-**Verify runs after every task.** `morph-spec verify` runs the build + test + validator chain relevant to your stack; a task closes when it is green and each `doneCriteria` has the evidence that proves it — red triggers an autonomous correction loop rather than a pause. Gate 3 is an independent evaluator that answers SHIP or FIX with evidence-typed blockers.
+**Verify runs once per feature.** `morph-spec verify {feature}` runs the build + test + validator chain relevant to your stack; red triggers an autonomous correction loop rather than a pause. Gate 3 is three independent sub-agents (verifier, reviewer, security when required) that answer SHIP or FIX with evidence-typed blockers.
 
 ---
 
@@ -379,4 +380,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.47.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v9.1.0 by [Polymorphism Tech](https://polymorphism.tech)*