@zrg-sh/studio 0.1.0

package/template/product-specs/hooks/studio-session-state.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# Studio Session State
+# PostToolUse hook: updates .planning/STATE.md after significant writes
+# Exit 0 always (non-blocking)
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only track docs/ writes
+if [[ ! "$FILE_PATH" == *"docs/"* ]]; then
+  exit 0
+fi
+
+# Skip templates
+if [[ "$FILE_PATH" == *"_template/"* ]] || [[ "$FILE_PATH" == *"_example/"* ]] || [[ "$FILE_PATH" == *"_golden/"* ]]; then
+  exit 0
+fi
+
+STATE_FILE=".planning/STATE.md"
+
+# Create .planning/ if needed
+mkdir -p .planning 2>/dev/null
+
+# Determine what was written
+if [[ "$FILE_PATH" == *"product-specs/docs/changes/"* ]]; then
+  PRDCT_DIR=$(echo "$FILE_PATH" | grep -oE "PRDCT-[0-9]+")
+  if [[ -n "$PRDCT_DIR" ]] && [[ -f "product-specs/docs/changes/$PRDCT_DIR/metadata.yaml" ]]; then
+    STATUS=$(grep "^status:" "product-specs/docs/changes/$PRDCT_DIR/metadata.yaml" | head -1 | sed 's/^status:[[:space:]]*//' | sed 's/[[:space:]]*#.*//')
+
+    # Update STATE.md
+    cat > "$STATE_FILE" << EOF
+# Studio State
+
+## Status: active
+## Current PRDCT: $PRDCT_DIR
+## Current Phase: $STATUS
+## Last Activity: $(date +%Y-%m-%dT%H:%M:%S)
+## Last File: $(basename "$FILE_PATH")
+
+## Session Continuity
+- Last stopped: $(date +%Y-%m-%dT%H:%M:%S)
+- Resume point: /studio-resume $PRDCT_DIR
+EOF
+  fi
+elif [[ "$FILE_PATH" == *"product-specs/docs/domains/"* ]]; then
+  DOMAIN=$(echo "$FILE_PATH" | sed 's|.*/product-specs/docs/domains/||' | cut -d/ -f1)
+  if [[ -n "$DOMAIN" ]] && [[ "$DOMAIN" != "_template" ]]; then
+    # Append domain activity to STATE.md if exists
+    if [[ -f "$STATE_FILE" ]]; then
+      echo "## Last Domain Activity: $DOMAIN ($(basename "$FILE_PATH")) at $(date +%H:%M)" >> "$STATE_FILE"
+    fi
+  fi
+fi
+
+exit 0

package/template/product-specs/hooks/studio-stage-gate.sh

@@ -0,0 +1,180 @@
+#!/bin/bash
+# Hook: PostToolUse for Write/Edit in product-specs/docs/changes/
+# Stage gate validation for 5-file change package
+# Validates change package conventions and stage gate transitions
+#
+# Input: JSON on stdin with tool_input
+# Exit 0 = ok, Exit 2 = block with message
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only check docs/changes files
+if [[ ! "$FILE_PATH" == *"product-specs/docs/changes/"* ]]; then
+  exit 0
+fi
+
+# Skip templates, examples, and golden
+if [[ "$FILE_PATH" == *"_template/"* ]] || [[ "$FILE_PATH" == *"_example/"* ]] || [[ "$FILE_PATH" == *"_golden/"* ]]; then
+  exit 0
+fi
+
+CHANGE_DIR=$(dirname "$FILE_PATH")
+FILE_NAME=$(basename "$FILE_PATH")
+
+# If metadata.yaml doesn't exist yet, skip (being created)
+if [[ ! -f "$CHANGE_DIR/metadata.yaml" ]]; then
+  exit 0
+fi
+
+# --- Basic metadata validation ---
+if ! grep -q "^id:" "$CHANGE_DIR/metadata.yaml"; then
+  echo "metadata.yaml missing 'id' field" >&2
+  exit 2
+fi
+if ! grep -q "^status:" "$CHANGE_DIR/metadata.yaml"; then
+  echo "metadata.yaml missing 'status' field" >&2
+  exit 2
+fi
+
+# --- Placeholder detection for any written file ---
+PLACEHOLDER_PATTERNS=(
+  "PRDCT-XXXX"
+  "YYYY-MM-DD"
+  "\[Feature name\]"
+  "\[Flow name\]"
+  "\[Aggregate name\]"
+  "\[Decision title\]"
+  "\[Surface name\]"
+)
+
+if [[ "$FILE_NAME" != "metadata.yaml" ]] && [[ -f "$FILE_PATH" ]]; then
+  for pattern in "${PLACEHOLDER_PATTERNS[@]}"; do
+    if grep -q "$pattern" "$FILE_PATH"; then
+      echo "WARNING: '$FILE_PATH' contains placeholder '$pattern'. Replace before advancing stage." >&2
+      # Warning only, don't block
+      break
+    fi
+  done
+fi
+
+# --- Stage gate validation on status transition ---
+if [[ "$FILE_NAME" == "metadata.yaml" ]]; then
+  NEW_STATUS=$(grep "^status:" "$FILE_PATH" | head -1 | sed 's/^status:[[:space:]]*//' | sed 's/[[:space:]]*#.*//')
+
+  # Helper: check file has content beyond template
+  has_content() {
+    local file="$CHANGE_DIR/$1"
+    if [[ ! -f "$file" ]]; then
+      return 1
+    fi
+    local content_lines
+    content_lines=$(grep -v "^---$" "$file" | grep -v "^#" | grep -v "^$" | grep -v "^<!--" | grep -v "^-$" | grep -v "^|---|" | wc -l | tr -d ' ')
+    [[ "$content_lines" -gt 3 ]]
+  }
+
+  # Helper: count list items in a section
+  list_items_in_section() {
+    local file="$CHANGE_DIR/$1"
+    local section="$2"
+    if [[ ! -f "$file" ]]; then
+      echo 0
+      return
+    fi
+    # Section ends at next h2 (^## ), not at h3+ subheaders (which are still part of the section).
+    # Counts items: numbered list, dash-bullet, OR h3/h4 scenario subheaders (e.g. "### Scenario HP-1").
+    awk "/^###? $section/{found=1;next} /^## /{if(found)exit} found" "$file" | grep -cE "^[0-9]+\.|^- \S|^###+ " | tr -d ' '
+  }
+
+  # Helper: check YAML field is not empty
+  field_not_empty() {
+    local field="$1"
+    local val
+    val=$(grep "^[[:space:]]*$field:" "$CHANGE_DIR/metadata.yaml" | head -1 | sed "s/^[[:space:]]*$field:[[:space:]]*//" | sed 's/[[:space:]]*#.*//' | sed 's/"//g')
+    [[ -n "$val" ]] && [[ "$val" != "\"\"" ]] && [[ "$val" != "''" ]]
+  }
+
+  # Helper: check YAML array field is not empty
+  array_not_empty() {
+    local field="$1"
+    local val
+    val=$(grep "^$field:" "$CHANGE_DIR/metadata.yaml" | head -1 | sed "s/^$field:[[:space:]]*//" | sed 's/[[:space:]]*#.*//')
+    [[ "$val" != "[]" ]] && [[ -n "$val" ]]
+  }
+
+  # Helper: count HTML files in mockups/ directory
+  mockup_html_count() {
+    local mockups_dir="$CHANGE_DIR/mockups"
+    if [[ ! -d "$mockups_dir" ]]; then
+      echo 0
+      return
+    fi
+    find "$mockups_dir" -maxdepth 1 -name "*.html" | wc -l | tr -d ' '
+  }
+
+  # Helper: count gherkin scenarios
+  gherkin_count() {
+    local file="$CHANGE_DIR/$1"
+    if [[ ! -f "$file" ]]; then
+      echo 0
+      return
+    fi
+    grep -cE "^Given|^Scenario(:| )|^### Scenario(:| )" "$file" | tr -d ' '
+  }
+
+  ERRORS=""
+
+  case "$NEW_STATUS" in
+    scenarios)
+      # Exit criteria for intent stage: intent → scenarios
+      has_content "01-intent.md" || ERRORS="$ERRORS\n  - 01-intent.md not filled"
+      field_not_empty "title" || ERRORS="$ERRORS\n  - metadata.yaml: title is empty"
+      field_not_empty "product" || ERRORS="$ERRORS\n  - metadata.yaml: product owner not set"
+      ;;
+
+    analysis)
+      # Exit criteria for scenarios stage: scenarios → analysis
+      has_content "02-scenarios.md" || ERRORS="$ERRORS\n  - 02-scenarios.md not filled"
+      local happy
+      happy=$(list_items_in_section "02-scenarios.md" "Happy path scenarios")
+      [[ "$happy" -ge 3 ]] || ERRORS="$ERRORS\n  - 02-scenarios.md: Happy path scenarios < 3 (found: $happy)"
+      local edges
+      edges=$(list_items_in_section "02-scenarios.md" "Edge case scenarios")
+      [[ "$edges" -ge 5 ]] || ERRORS="$ERRORS\n  - 02-scenarios.md: Edge case scenarios < 5 (found: $edges)"
+      ;;
+
+    domain)
+      # Exit criteria for analysis stage: analysis → domain
+      has_content "03-analysis.md" || ERRORS="$ERRORS\n  - 03-analysis.md not filled"
+      # Iron rule 1: scenarios must be complete before domain
+      has_content "02-scenarios.md" || ERRORS="$ERRORS\n  - IRON RULE: 02-scenarios.md must be complete before domain"
+      ;;
+
+    ux)
+      # Exit criteria for domain stage: domain → ux
+      has_content "04-domain.md" || ERRORS="$ERRORS\n  - 04-domain.md not filled"
+      array_not_empty "domains" || ERRORS="$ERRORS\n  - metadata.yaml: domains is empty"
+      # Iron rule 2: analysis must be complete
+      has_content "03-analysis.md" || ERRORS="$ERRORS\n  - IRON RULE: 03-analysis.md must be complete before UX"
+      # Iron rule 3: domain must be complete
+      has_content "04-domain.md" || ERRORS="$ERRORS\n  - IRON RULE: 04-domain.md must be complete before UX"
+      ;;
+
+    done)
+      # Exit criteria for ux stage: ux → done
+      has_content "05-ux.md" || ERRORS="$ERRORS\n  - 05-ux.md not filled"
+      local html_count
+      html_count=$(mockup_html_count)
+      [[ "$html_count" -ge 1 ]] || ERRORS="$ERRORS\n  - mockups/: no HTML files found (need at least 1)"
+      # Iron rule 4: scenarios must be complete
+      has_content "02-scenarios.md" || ERRORS="$ERRORS\n  - IRON RULE: 02-scenarios.md must be complete before done"
+      ;;
+  esac
+
+  if [[ -n "$ERRORS" ]]; then
+    echo "Stage gate BLOCKED: transition to '$NEW_STATUS' not possible:$ERRORS" >&2
+    exit 2
+  fi
+fi
+
+exit 0

package/template/product-specs/references/checkpoints.md

@@ -0,0 +1,27 @@
+# Checkpoint protocol
+
+Точки взаимодействия с человеком. Золотое правило: **если AI может автоматизировать — AI автоматизирует**. Человек только подтверждает.
+
+## 3 типа чекпоинтов
+
+### checkpoint:human-verify (90% случаев)
+AI сделал всё автоматически. Человек подтверждает результат.
+- Пример: "Я создал 03-domain-impact.md. Проверь что домены определены верно."
+- Протокол: показать summary → ждать "ок" → продолжить
+
+### checkpoint:decision (9% случаев)
+Есть несколько валидных вариантов. Человек выбирает.
+- Пример: "Это новый домен или расширение существующего? Варианты: A) новый домен assessment, B) расширить training-session"
+- Протокол: показать варианты с trade-offs → ждать выбора → записать в 09-decisions.md
+
+### checkpoint:human-action (1% случаев)
+Действие, которое может выполнить только человек.
+- Пример: "Нужен API key для Stripe. Создай в dashboard и вставь в .env"
+- Протокол: описать что нужно → ждать подтверждения → продолжить
+
+## Когда НЕ останавливаться
+- Создание файлов и директорий
+- Обновление metadata.yaml
+- Обновление domain docs
+- Git commit
+- Linear sync

package/template/product-specs/references/ddd-conventions.md

@@ -0,0 +1,38 @@
+# DDD conventions
+
+## Domain docs structure
+Каждый домен = папка с 13 файлами:
+
+### Core (бизнес-знание)
+1. README.md — что делает, границы (inside/outside)
+2. ubiquitous-language.md — термины, определения, запрещённые синонимы
+3. aggregates.md — корень агрегата, state machine, ER diagram
+4. business-rules.md — правила с rationale и edge cases
+5. events.md — события, producers, consumers, payload, guarantees
+6. invariants.md — неломаемые правила (чеклист)
+7. scenarios.md — каноничные Gherkin сценарии (happy path, edge, error, permissions, concurrent)
+8. integrations.md — upstream/downstream, контракты, SLA
+9. ownership.md — кто владеет, кто апрувит, эскалация
+
+### Technical (реализация)
+10. api-contracts.md — owned/consumed endpoints
+11. data-model.md — DB schema, таблицы, индексы
+12. operational-sla.md — performance targets, timeouts, monitoring
+
+### History
+13. changelog.md — автоистория изменений домена
+
+## Principles
+- Aggregate = consistency boundary, one transaction
+- References between aggregates ONLY by ID
+- Each term defined in EXACTLY one domain
+- Invariants are STRONGER than business rules (invariants cannot be broken, rules can have exceptions)
+- Events in PastTense format (SessionStarted, TurnCompleted)
+- Prefer many small domains over one god-domain
+
+## Domain docs contain ONLY business knowledge
+- NO UI components
+- NO service names
+- NO implementation details
+- NO code snippets
+- After PRDCT merge: only business rules, aggregates, events, invariants go to domain docs

package/template/product-specs/references/gates.md

@@ -0,0 +1,50 @@
+# Gate types
+
+Gates control transitions between pipeline stages. Each gate is a check before admission to the next stage.
+
+## 4 gate types
+
+### Pre-flight gate
+Validates preconditions BEFORE work begins.
+- Example: Before 02-scenarios -> check that 01-intent.md exists and is filled
+- On failure: BLOCK entry, report what is missing
+
+### Revision gate
+Evaluates OUTPUT quality after completion. May send back for rework.
+- Example: After 02-scenarios -> check that >= 5 edge cases exist
+- On failure: RETURN to author with feedback (max 3 iterations)
+- Stall detection: if after 3 iterations quality has not improved -> escalation
+
+### Escalation gate
+Problem that AI cannot resolve on its own.
+- Example: Domain invariant violated, conflict between PRDCTs
+- Action: STOP, show to user, wait for decision
+
+### Abort gate
+Immediate stop to prevent damage.
+- Example: Context < 25%, iron rule violated
+- Action: Save state, halt execution
+
+## 5 iron rules (abort gates)
+
+These are non-negotiable. Violation triggers an immediate abort.
+
+1. **No scenarios -> can't analyze.** If 02-scenarios.md is not complete, stage 03 is blocked.
+2. **No analysis -> can't model domain.** If 03-analysis.md is not complete, stage 04 is blocked.
+3. **No domain -> can't do UX.** If 04-domain.md is not complete, stage 05 is blocked.
+4. **No scenarios -> can't finalize UX.** If 02-scenarios.md is not complete, 05-ux cannot be finalized.
+5. **Canon not edited directly.** Domain docs are only updated through merger after change is done.
+
+## Gate matrix
+
+| Transition | Pre-flight | Revision | Escalation | Abort |
+|---|---|---|---|---|
+| intent -> scenarios | 01-intent.md filled, metadata.yaml has title + owners | -- | -- | -- |
+| scenarios -> analysis | 02-scenarios.md filled, >= 5 edge cases | Cross-review by Analyst (technically possible?) | -- | **Iron rule 1**: no scenarios |
+| analysis -> domain | 03-analysis.md filled, system impact assessed | Analysis consistent with scenarios | -- | context < 25% |
+| domain -> ux | 04-domain.md filled, domains identified | Domain model consistent | Domain invariant violated | **Iron rule 2**: no analysis |
+| ux -> done | 05-ux.md filled, >= 1 mockup HTML | Surfaces cover all scenarios, all states represented | -- | **Iron rule 3**: no domain, **Iron rule 4**: no scenarios |
+
+## Placeholder detection
+Gate hooks warn (without blocking) if a file contains placeholder text from templates:
+`PRDCT-XXXX`, `YYYY-MM-DD`, `[Feature name]`, `[Flow name]`, `[Aggregate name]`, `[Decision title]`, `[Surface name]`

package/template/product-specs/references/model-profiles.md

@@ -0,0 +1,28 @@
+# Model profiles
+
+Каждый agent может использовать разную модель в зависимости от сложности задачи.
+
+## Profiles
+
+| Profile | Description | Use case |
+|---------|-------------|----------|
+| quality | Всегда Opus 4.6 | Критические решения, архитектура |
+| balanced | Opus для reasoning, Sonnet для execution | Стандартная работа |
+| budget | Sonnet для reasoning, Haiku для execution | Высокий объём, низкая сложность |
+| inherit | Модель текущей сессии | Sub-agents внутри сессии |
+
+## Agent → model mapping (balanced profile)
+
+| Agent | Model tier | Reasoning |
+|-------|-----------|-----------|
+| studio-pm | opus | Извлечение бизнес-требований — reasoning-heavy |
+| studio-analyst | opus | DDD, инварианты — высокая сложность |
+| studio-designer | sonnet | HTML/CSS генерация — execution-heavy |
+| studio-backend | opus | Архитектурные решения |
+| studio-frontend | sonnet | UI states — structured output |
+| studio-qa | sonnet | Test cases — structured output |
+| studio-verifier | opus | Goal-backward verification — reasoning-heavy |
+| studio-reviewer | sonnet | Cross-reference — pattern matching |
+| studio-codebase-mapper | sonnet | Code reading — high volume |
+| studio-domain-extractor | opus | Domain modeling — reasoning-heavy |
+| studio-conflict-resolver | opus | Conflict analysis — judgment |

package/template/product-specs/references/obsidian-conventions.md

@@ -0,0 +1,51 @@
+---
+paths:
+  - "docs/**"
+---
+
+# Obsidian-specific conventions
+
+## Vault structure
+- Obsidian — основной инструмент для работы с документацией
+- Vault root: `docs/`
+- Canvas файлы (`.canvas`): в `_meta/` для визуальных карт
+- Dataview дашборды: `domains-dashboard.md`, `changes-dashboard.md`
+
+## Graph view optimization
+- Каждый файл ДОЛЖЕН иметь осмысленное имя (НЕ `index.md`)
+- Frontmatter `tags:` используются для группировки и цветов в graph view
+- Рекомендуемые группы в graph:
+  - `path:"domains"` → синий (бизнес-домены)
+  - `path:"changes"` → зелёный (change packages)
+  - `path:"adrs"` → фиолетовый (решения)
+  - `path:"contexts"` → оранжевый (платформа)
+  - `path:"_meta"` → серый (метаданные)
+
+## Canvas files
+- Формат: JSON Canvas (открытый стандарт)
+- Nodes: embed domain README.md через `type: "file"`
+- Edges: подписи = domain events или API contracts
+- Colors: `"4"` = active, `"6"` = planned, `"0"` = infrastructure
+
+## Dataview patterns
+```
+# Таблица из frontmatter:
+TABLE field1, field2 FROM "folder" WHERE type = "X" SORT field1
+
+# Задачи из чеклистов:
+TASK FROM "folder" WHERE file.name = "invariants"
+
+# Группировка:
+TABLE status FROM "changes" WHERE type = "change" GROUP BY status
+```
+
+## Embeds
+- Используй `![[file]]` для встраивания в дашборды
+- Используй `![[file#heading]]` для встраивания секции
+- Canvas: `type: "file"` для embed из vault
+
+## Plugins required
+- **Dataview** — живые дашборды, запросы по frontmatter
+- **Templater** (optional) — динамическое создание файлов из шаблонов
+- **Kanban** (optional) — kanban-доски из markdown
+- **Mermaid** — встроен в Obsidian, доп. плагин не нужен

package/template/product-specs/references/stage-pipeline.md

@@ -0,0 +1,65 @@
+# Stage pipeline
+
+## Three layers
+
+```
+LAYER 1 — WHAT & WHY (problem space)
+  01-intent.md          PM
+  02-scenarios.md       Scenario Writer + QA
+
+LAYER 2 — HOW IT WORKS (system space)
+  03-analysis.md        Analyst
+  04-domain.md          Domain Framer + PM
+
+LAYER 3 — HOW IT LOOKS (solution space)
+  05-ux.md + mockups/   Designer
+```
+
+After UX is complete, the change package is DONE.
+Executor writes code from domain docs + scenarios + UX.
+Merger updates domain docs after code is merged.
+
+## Status flow
+`intent -> scenarios -> analysis -> domain -> ux -> done`
+
+## Naming convention
+`PRDCT-XXXX-feature-name` (e.g. `PRDCT-0001-user-invites`)
+
+## Parallel stages
+After 02-scenarios is complete:
+- Analyst (03-analysis) and Domain Framer (04-domain) work sequentially
+- Designer (05-ux) can start exploring but requires completed 04-domain before finalizing
+
+## Iron rules (gate rules)
+
+1. **No scenarios -> can't analyze.** Stage 03 requires completed 02-scenarios.md. Without scenarios, analysis has no behavior to ground on.
+2. **No analysis -> can't model domain.** Stage 04 requires completed 03-analysis.md. Without system analysis, domain modeling lacks technical grounding.
+3. **No domain -> can't do UX.** Stage 05 requires completed 04-domain.md. Without domain boundaries, UX decisions have no grounding.
+4. **No scenarios -> can't finalize UX.** Stage 05 requires completed 02-scenarios.md. Without scenarios, UX has no behavior to show.
+5. **Canon not edited directly.** Domain docs are ONLY updated through merger after change is done. Direct edits are forbidden.
+
+## Cross-review matrix
+
+Each stage output is reviewed by a different role before the next stage begins.
+
+| Stage output | Reviewed by | Review question |
+|---|---|---|
+| 01-intent (PM) | Analyst | Is the problem clear? Are boundaries well-defined? |
+| 02-scenarios (Scenario Writer) | Analyst | Are all scenarios technically possible? Edge cases covered? |
+| 03-analysis (Analyst) | PM | Does the system analysis match the business intent? |
+| 04-domain (Domain Framer) | Analyst | Does the domain model cover all scenarios? Invariants correct? |
+| 05-ux (Designer) | QA | Do surfaces cover all scenarios? All states represented? |
+
+## Iteration rules
+If a later role finds a problem in a previous stage:
+1. Record in the relevant stage document under an `## Open questions` section
+2. If critical (changes scope) -> STOP, escalation gate
+3. If non-critical -> record, continue
+4. On return -> cascade update all downstream documents
+
+## Post-change flow
+
+After status becomes `done`:
+1. **Executor** reads domain docs + scenarios + UX -> writes code
+2. **Merger** reads change package -> updates domain docs (aggregates, rules, events, invariants, UL, scenarios, surfaces)
+3. Change package is FROZEN after merge

package/template/product-specs/rules/change-management.md

@@ -0,0 +1,159 @@
+---
+paths:
+  - "product-specs/docs/changes/**"
+---
+
+# Change management rules
+
+## Change package structure
+Each change package is a folder `PRDCT-XXXX-feature-name/` with the following files:
+```
+metadata.yaml       -> Machine-readable metadata
+01-intent.md        -> What and why (PM)
+02-scenarios.md     -> User scenarios, edge cases (Scenario Writer + QA)
+03-analysis.md      -> System analysis (Analyst)
+04-domain.md        -> Domain impact (Domain Framer + PM)
+05-ux.md            -> UX design decisions (Designer)
+mockups/            -> HTML mockup files
+```
+
+## Naming convention
+- Format: `PRDCT-XXXX-feature-name` (e.g. `PRDCT-0001-user-invites`)
+- XXXX is zero-padded, incrementing
+- Feature name is kebab-case, descriptive
+
+## Status flow
+```
+intent -> scenarios -> analysis -> domain -> ux -> done
+```
+
+## Stage pipeline
+```
+LAYER 1 -- WHAT & WHY
+  01-intent.md          PM
+  02-scenarios.md       Scenario Writer + QA
+
+LAYER 2 -- HOW IT WORKS
+  03-analysis.md        Analyst
+  04-domain.md          Domain Framer + PM
+
+LAYER 3 -- HOW IT LOOKS
+  05-ux.md + mockups/   Designer
+```
+
+## Iron rules (gate rules)
+
+These are non-negotiable. Violation blocks the pipeline.
+
+1. **No scenarios -> can't analyze.** Stage 03 requires completed 02-scenarios.md.
+2. **No analysis -> can't model domain.** Stage 04 requires completed 03-analysis.md.
+3. **No domain -> can't do UX.** Stage 05 requires completed 04-domain.md.
+4. **No scenarios -> can't finalize UX.** Stage 05 requires completed 02-scenarios.md.
+5. **Canon not edited directly.** Domain docs are ONLY updated through merger after change is done.
+
+ID numbering is governed by [`id-numbering.md`](./id-numbering.md). Stage agents allocate via `_id-counters.json`. Merger verifies preservation.
+
+## Cross-review rules
+
+Each stage output is reviewed by a different role before the next stage begins.
+
+| Stage output | Reviewed by | Review question |
+|---|---|---|
+| 01-intent (PM) | Analyst | Is the problem clear? Are boundaries well-defined? |
+| 02-scenarios (Scenario Writer) | Analyst | Are all scenarios technically possible? Edge cases covered? |
+| 03-analysis (Analyst) | PM | Does the system analysis match the business intent? |
+| 04-domain (Domain Framer) | Analyst | Does the domain model cover all scenarios? Invariants correct? |
+| 05-ux (Designer) | QA | Do surfaces cover all scenarios? All states represented? |
+
+## Stage gates
+
+Transition between stages is controlled by validation hooks. When `status` changes in metadata.yaml, the hook checks exit criteria.
+
+### intent -> scenarios
+- [ ] `01-intent.md` filled (not placeholder)
+- [ ] `metadata.yaml` -> title not empty
+- [ ] `metadata.yaml` -> owners.product specified
+
+### scenarios -> analysis
+- [ ] `02-scenarios.md` filled
+- [ ] Happy path contains >= 3 steps
+- [ ] Edge cases contain >= 5 items
+- [ ] Cross-review by Analyst complete (technically possible?)
+
+### analysis -> domain
+- [ ] `03-analysis.md` filled
+- [ ] System impact assessed
+- [ ] Analysis consistent with scenarios
+
+### domain -> ux
+- [ ] `04-domain.md` filled
+- [ ] Domains identified and listed
+- [ ] Domain model is internally consistent
+- [ ] **Iron rule 2**: 03-analysis.md must be complete
+
+### ux -> done
+- [ ] `05-ux.md` filled
+- [ ] >= 1 mockup HTML in `mockups/`
+- [ ] Surfaces cover all scenarios from 02-scenarios.md
+- [ ] All surface states represented (loading, success, error, empty)
+- [ ] Cross-review by QA complete
+
+## Post-change flow
+
+After status becomes `done`:
+1. **Executor** reads domain docs + scenarios + UX -> writes code
+2. **Merger** reads change package -> updates domain docs
+3. Change package is FROZEN after merge
+
+## Iteration rules
+- If a later stage discovers a problem in a previous stage:
+  1. Record the issue in the relevant document under `## Open questions`
+  2. Update the source document
+  3. Cascade update all downstream documents
+  4. If the issue changes scope -> STOP, escalation gate
+- Cascade updates are mandatory -- no downstream doc may reference stale upstream content
+
+## Metadata rules
+- `id`: unique, incrementing PRDCT-XXXX
+- `status`: updated at each transition (intent|scenarios|analysis|domain|ux|done)
+- `owners`: filled at intent stage
+- `domains`: filled at domain stage
+
+## Immutability
+- After merge, a change package is FROZEN
+- Fixes go into a new PRDCT with `related_changes` reference
+- No retroactive edits to merged packages
+
+## Conflict resolution
+
+Two change packages may modify the same domain simultaneously. This is normal but requires explicit management.
+
+### Detection
+When creating or updating a change package, the AI role MUST:
+1. Scan all active PRDCTs (status != done) via `ls product-specs/docs/changes/`
+2. Read `metadata.yaml` of each active PRDCT
+3. Compare `domains` and `capabilities` fields
+4. If overlap found -> declare CONFLICT
+
+### Notification
+On conflict detection:
+1. Add entry to `metadata.yaml` -> `conflicts_with`
+2. Add question in the relevant stage doc with tag `[CONFLICT]`
+3. Notify user: which PRDCT conflicts and on which domains
+
+### Resolution
+1. Identify domain owner from `product-specs/docs/domains/[name]/ownership.md`
+2. Domain owner is arbiter, decides priority
+3. Lower-priority PRDCT gets `blocked_by: PRDCT-XXXX`
+4. After higher-priority PRDCT merges, lower-priority must:
+   - Rebase domain impact (04-domain.md)
+   - Re-check invariants
+
+### Tracking
+Update `conflicts_with` entry:
+- `resolution: resolved`
+- `resolution_note: "description of how it was resolved"`
+
+## Placeholder detection
+Gate hooks warn (without blocking) if a file contains placeholder text from templates:
+`PRDCT-XXXX`, `YYYY-MM-DD`, `[Feature name]`, `[Flow name]`, `[Aggregate name]`, `[Decision title]`, `[Surface name]`