prizmkit 1.1.111 → 1.1.112

package/bundled/dev-pipeline/tests/test_python_runner_parity.py

@@ -61,6 +61,35 @@ def _write_feature_list(paths):
     )
 
 
+def _write_family_plan(paths, kind, items):
+    plan_config = {
+        "feature": (paths.feature_plan, "features", "dev-pipeline-feature-list-v1"),
+        "bugfix": (paths.bugfix_plan, "bugs", "dev-pipeline-bug-fix-list-v1"),
+        "refactor": (paths.refactor_plan, "refactors", "dev-pipeline-refactor-list-v1"),
+    }
+    plan_path, list_key, schema = plan_config[kind]
+    plan_path.write_text(
+        json.dumps({"$schema": schema, "project_name": "Fake", list_key: items}),
+        encoding="utf-8",
+    )
+    return plan_path
+
+
+def _get_next_result(kind, paths):
+    from prizmkit_runtime.runner_models import family_for, parse_invocation
+    from prizmkit_runtime.runner_status import get_next
+
+    family = family_for(kind, paths)
+    invocation = parse_invocation(family, "run", ())
+    invocation = invocation.__class__(**{**invocation.__dict__, "list_path": family.plan_path})
+    return get_next(family, invocation, paths.project_root)
+
+
+def _item_id_from_next_result(kind, result):
+    key = {"feature": "feature_id", "bugfix": "bug_id", "refactor": "refactor_id"}[kind]
+    return result.data[key]
+
+
 def test_retired_shell_runtime_files_are_absent_from_source():
     retired = [
         "run-feature.sh",
@@ -360,6 +389,174 @@ def test_status_bridge_preserves_feature_filter_selection(tmp_path):
     assert update.data["context_overflow_count"] == 1
 
 
+def test_status_bridge_uses_stable_dependency_order_across_pipeline_families(tmp_path):
+    cases = {
+        "feature": [
+            {"id": "F-001", "title": "Blocked", "status": "pending", "priority": "critical", "dependencies": ["F-002"]},
+            {"id": "F-002", "title": "First", "status": "pending", "priority": "low", "dependencies": []},
+            {"id": "F-003", "title": "Independent", "status": "pending", "priority": "high", "dependencies": []},
+        ],
+        "bugfix": [
+            {"id": "B-001", "title": "Blocked", "status": "pending", "severity": "critical", "priority": "high", "error_source": {"type": "user_report"}, "verification_type": "manual", "acceptance_criteria": ["fixed"], "dependencies": ["B-002"]},
+            {"id": "B-002", "title": "First", "status": "pending", "severity": "low", "priority": "low", "error_source": {"type": "user_report"}, "verification_type": "manual", "acceptance_criteria": ["fixed"], "dependencies": []},
+            {"id": "B-003", "title": "Independent", "status": "pending", "severity": "high", "priority": "high", "error_source": {"type": "user_report"}, "verification_type": "manual", "acceptance_criteria": ["fixed"], "dependencies": []},
+        ],
+        "refactor": [
+            {"id": "R-001", "title": "Blocked", "description": "blocked", "scope": {}, "type": "restructure", "priority": "critical", "complexity": "high", "behavior_preservation": {"strategy": "test-gate"}, "acceptance_criteria": ["done"], "dependencies": ["R-002"], "status": "pending"},
+            {"id": "R-002", "title": "First", "description": "first", "scope": {}, "type": "extract", "priority": "low", "complexity": "low", "behavior_preservation": {"strategy": "test-gate"}, "acceptance_criteria": ["done"], "dependencies": [], "status": "pending"},
+            {"id": "R-003", "title": "Independent", "description": "independent", "scope": {}, "type": "simplify", "priority": "high", "complexity": "medium", "behavior_preservation": {"strategy": "test-gate"}, "acceptance_criteria": ["done"], "dependencies": [], "status": "pending"},
+        ],
+    }
+
+    for kind, items in cases.items():
+        paths = _make_paths(tmp_path / f"stable-{kind}")
+        _write_family_plan(paths, kind, items)
+
+        result = _get_next_result(kind, paths)
+
+        assert result.ok
+        assert _item_id_from_next_result(kind, result) == {"feature": "F-002", "bugfix": "B-002", "refactor": "R-002"}[kind]
+
+
+def test_status_bridge_prefers_in_progress_items_with_satisfied_dependencies(tmp_path):
+    cases = {
+        "feature": [
+            {"id": "F-001", "title": "Done", "status": "completed", "priority": "low", "dependencies": []},
+            {"id": "F-002", "title": "Resume", "status": "in_progress", "priority": "low", "dependencies": ["F-001"]},
+            {"id": "F-003", "title": "Pending", "status": "pending", "priority": "critical", "dependencies": []},
+        ],
+        "bugfix": [
+            {"id": "B-001", "title": "Done", "status": "completed", "severity": "low", "priority": "low", "error_source": {"type": "user_report"}, "verification_type": "manual", "acceptance_criteria": ["fixed"], "dependencies": []},
+            {"id": "B-002", "title": "Resume", "status": "in_progress", "severity": "low", "priority": "low", "error_source": {"type": "user_report"}, "verification_type": "manual", "acceptance_criteria": ["fixed"], "dependencies": ["B-001"]},
+            {"id": "B-003", "title": "Pending", "status": "pending", "severity": "critical", "priority": "high", "error_source": {"type": "user_report"}, "verification_type": "manual", "acceptance_criteria": ["fixed"], "dependencies": []},
+        ],
+        "refactor": [
+            {"id": "R-001", "title": "Done", "description": "done", "scope": {}, "type": "extract", "priority": "low", "complexity": "low", "behavior_preservation": {"strategy": "test-gate"}, "acceptance_criteria": ["done"], "dependencies": [], "status": "completed"},
+            {"id": "R-002", "title": "Resume", "description": "resume", "scope": {}, "type": "extract", "priority": "low", "complexity": "low", "behavior_preservation": {"strategy": "test-gate"}, "acceptance_criteria": ["done"], "dependencies": ["R-001"], "status": "in_progress"},
+            {"id": "R-003", "title": "Pending", "description": "pending", "scope": {}, "type": "migrate", "priority": "critical", "complexity": "high", "behavior_preservation": {"strategy": "test-gate"}, "acceptance_criteria": ["done"], "dependencies": [], "status": "pending"},
+        ],
+    }
+
+    for kind, items in cases.items():
+        paths = _make_paths(tmp_path / f"resume-{kind}")
+        _write_family_plan(paths, kind, items)
+
+        result = _get_next_result(kind, paths)
+
+        assert result.ok
+        assert _item_id_from_next_result(kind, result) == {"feature": "F-002", "bugfix": "B-002", "refactor": "R-002"}[kind]
+
+
+def test_refactor_dependencies_require_completed_not_other_terminal_statuses(tmp_path):
+    paths = _make_paths(tmp_path)
+    _write_family_plan(
+        paths,
+        "refactor",
+        [
+            {"id": "R-001", "title": "Failed Dependency", "description": "failed", "scope": {}, "type": "extract", "priority": "high", "complexity": "low", "behavior_preservation": {"strategy": "test-gate"}, "acceptance_criteria": ["done"], "dependencies": [], "status": "failed"},
+            {"id": "R-002", "title": "Blocked", "description": "blocked", "scope": {}, "type": "restructure", "priority": "high", "complexity": "medium", "behavior_preservation": {"strategy": "test-gate"}, "acceptance_criteria": ["done"], "dependencies": ["R-001"], "status": "pending"},
+        ],
+    )
+
+    result = _get_next_result("refactor", paths)
+
+    assert result.ok
+    assert result.text == "PIPELINE_BLOCKED"
+    assert result.data is None
+
+
+def test_init_scripts_reject_missing_self_and_cycle_dependencies(tmp_path):
+    script_config = {
+        "feature": ("init-pipeline.py", "--feature-list", "F-", "missing dependency"),
+        "bugfix": ("init-bugfix-pipeline.py", "--bug-list", "B-", "missing dependency"),
+        "refactor": ("init-refactor-pipeline.py", "--refactor-list", "R-", "missing dependency"),
+    }
+    scenarios = {
+        "missing": lambda kind, prefix: _family_items(kind, [
+            (f"{prefix}001", [f"{prefix}999"], "pending"),
+        ]),
+        "self": lambda kind, prefix: _family_items(kind, [
+            (f"{prefix}001", [f"{prefix}001"], "pending"),
+        ]),
+        "cycle": lambda kind, prefix: _family_items(kind, [
+            (f"{prefix}001", [f"{prefix}002"], "pending"),
+            (f"{prefix}002", [f"{prefix}001"], "pending"),
+        ]),
+    }
+    expected_fragments = {
+        "missing": "missing dependency",
+        "self": "cannot depend on itself",
+        "cycle": "Dependency cycle detected",
+    }
+
+    for kind, (script_name, list_arg, prefix, _missing_fragment) in script_config.items():
+        for scenario, build_items in scenarios.items():
+            paths = _make_paths(tmp_path / f"init-{kind}-{scenario}")
+            plan_path = _write_family_plan(paths, kind, build_items(kind, prefix))
+            result = subprocess.run(
+                [
+                    PYTHON_310_PLUS,
+                    str(PIPELINE_ROOT / "scripts" / script_name),
+                    list_arg,
+                    str(plan_path),
+                    "--state-dir",
+                    str(paths.project_root / ".prizmkit" / "state" / f"init-{kind}-{scenario}"),
+                ],
+                cwd=REPO_ROOT,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                check=False,
+            )
+
+            assert result.returncode == 1, (kind, scenario, result.stdout, result.stderr)
+            payload = json.loads(result.stdout)
+            assert any(expected_fragments[scenario] in error for error in payload["errors"])
+
+
+def _family_items(kind, entries):
+    items = []
+    for item_id, dependencies, status in entries:
+        if kind == "feature":
+            items.append({
+                "id": item_id,
+                "title": item_id,
+                "description": "Implement this feature with enough detail for initialization validation.",
+                "priority": "medium",
+                "dependencies": dependencies,
+                "acceptance_criteria": ["done"],
+                "status": status,
+            })
+        elif kind == "bugfix":
+            items.append({
+                "id": item_id,
+                "title": item_id,
+                "description": "Bug description",
+                "severity": "medium",
+                "priority": "medium",
+                "error_source": {"type": "user_report"},
+                "verification_type": "manual",
+                "acceptance_criteria": ["fixed"],
+                "dependencies": dependencies,
+                "status": status,
+            })
+        else:
+            items.append({
+                "id": item_id,
+                "title": item_id,
+                "description": "Refactor description",
+                "scope": {},
+                "type": "extract",
+                "priority": "medium",
+                "complexity": "low",
+                "behavior_preservation": {"strategy": "test-gate"},
+                "acceptance_criteria": ["done"],
+                "dependencies": dependencies,
+                "status": status,
+            })
+    return items
+
+
 def test_status_bridge_passes_max_retries_from_invocation_or_environment(monkeypatch, tmp_path):
     import subprocess
     from prizmkit_runtime.runner_models import family_for, parse_invocation

package/bundled/dev-pipeline/tests/test_unified_cli.py

@@ -458,7 +458,7 @@ def test_interoperability_preserves_existing_utility_mapping():
     explicitly_library_only = set(UTILITY_LIBRARY_ONLY)
 
     assert actual_scripts == mapped_scripts | explicitly_library_only
-    assert explicitly_library_only == {"continuation.py", "utils.py"}
+    assert explicitly_library_only == {"continuation.py", "prompt_framework.py", "utils.py"}
     assert "parse-stream-progress.py" in mapped_scripts
     assert "prizmkit-test-gate.py" not in mapped_scripts
 
@@ -803,7 +803,11 @@ def test_headless_subagent_prompt_guidance_keeps_no_worktree_boundary_visible():
 
     for path in guidance_files:
         text = path.read_text(encoding="utf-8")
-        assert "default/no worktree" in text, path
+        assert (
+            "default/no worktree" in text
+            or "current-workspace / active-checkout / no-worktree" in text
+            or "current workspace / active checkout / no worktree" in text
+        ), path
         assert "do not request or create" in text.lower() or "do not request worktree isolation" in text.lower(), path
         assert ".claude/worktrees/..." in text, path
         assert ".prizmkit/state/worktrees/..." in text, path

package/bundled/dev-pipeline/tests/test_utils.py

@@ -4,7 +4,13 @@ import json
 import os
 import tempfile
 
-from utils import load_json_file, write_json_file, pad_right, _build_progress_bar
+from utils import (
+    load_json_file,
+    write_json_file,
+    pad_right,
+    _build_progress_bar,
+    stable_topological_order,
+)
 
 
 # ---------------------------------------------------------------------------
@@ -80,3 +86,62 @@ class TestBuildProgressBar:
     def test_fifty_percent(self):
         bar = _build_progress_bar(50, width=10)
         assert "50%" in bar
+
+
+# ---------------------------------------------------------------------------
+# stable_topological_order
+# ---------------------------------------------------------------------------
+
+class TestStableTopologicalOrder:
+    def test_dependencies_precede_dependents_with_stable_tie_breaking(self):
+        items = [
+            {"id": "F-001", "dependencies": []},
+            {"id": "F-002", "dependencies": ["F-001"]},
+            {"id": "F-003", "dependencies": []},
+        ]
+
+        ordered, errors = stable_topological_order(items, item_label="Feature")
+
+        assert errors == []
+        assert [item["id"] for item in ordered] == ["F-001", "F-002", "F-003"]
+
+    def test_unrelated_items_preserve_original_list_order(self):
+        items = [
+            {"id": "F-010", "dependencies": []},
+            {"id": "F-002", "dependencies": []},
+            {"id": "F-007", "dependencies": []},
+        ]
+
+        ordered, errors = stable_topological_order(items, item_label="Feature")
+
+        assert errors == []
+        assert [item["id"] for item in ordered] == ["F-010", "F-002", "F-007"]
+
+    def test_missing_dependency_is_blocking_error(self):
+        items = [
+            {"id": "B-001", "dependencies": ["B-999"]},
+        ]
+
+        _ordered, errors = stable_topological_order(items, item_label="Bug")
+
+        assert errors == ["Bug 'B-001' depends on missing dependency 'B-999'"]
+
+    def test_self_dependency_is_blocking_error(self):
+        items = [
+            {"id": "R-001", "dependencies": ["R-001"]},
+        ]
+
+        _ordered, errors = stable_topological_order(items, item_label="Refactor")
+
+        assert errors == ["Refactor 'R-001' cannot depend on itself"]
+
+    def test_cycle_reports_chain(self):
+        items = [
+            {"id": "F-001", "dependencies": ["F-003"]},
+            {"id": "F-002", "dependencies": ["F-001"]},
+            {"id": "F-003", "dependencies": ["F-002"]},
+        ]
+
+        _ordered, errors = stable_topological_order(items, item_label="Feature")
+
+        assert errors == ["Dependency cycle detected: F-001 -> F-003 -> F-002 -> F-001"]

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.111",
+  "version": "1.1.112",
   "skills": {
     "prizmkit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/bundled/skills/app-planner/SKILL.md

@@ -35,10 +35,11 @@ If you believe the task is better suited for a different workflow, you MUST:
 
 **Your ONLY writable outputs are:**
 1. `.prizmkit/plans/project-brief.md` (`.prizmkit/plans/` — accumulated project context brief)
-2. Project conventions and architecture decisions appended to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` (with user consent)
-3. Infrastructure configuration (database conventions, deployment config, **cloud services**) appended to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` section
-4. `.prizmkit/rules/<layer>-rules.md` — per-layer development rules generated by Rules Configuration
-5. `.prizmkit/prizm-docs/root.prizm` — `RULES:` pointer line only (not other root.prizm content; created minimally if absent)
+2. `.prizmkit/plans/project-brief.draft.md` — draft only when user exits before completion
+3. Project conventions and architecture decisions appended to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` (with user consent)
+4. Infrastructure configuration (database conventions, deployment config, **cloud services**) appended to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` section
+5. `.prizmkit/rules/<layer>-rules.md` — per-layer development rules generated by Rules Configuration
+6. `.prizmkit/prizm-docs/root.prizm` — `RULES:` pointer line only (not other root.prizm content; created minimally if absent)
 
 **Project instruction file selection**:
 - If `.prizmkit/manifest.json` exists, use its `platform` field as the source of truth.
@@ -172,7 +173,7 @@ Route by answer:
   - After brainstorm completes, use `AskUserQuestion`: "Ideas are taking shape. What's next?"
     - **Continue to project planning (Recommended)** — capture tech stack, conventions, and architecture decisions
     - **Continue refining** — keep brainstorming
-    - **Save draft & exit** — save progress to .prizmkit/planning/
+    - **Save draft & exit** — save progress to `.prizmkit/plans/project-brief.draft.md`
   - **Checkpoints in explore mode**: CP-AP-0 (required), CP-AP-1 (required), CP-AP-2 (from brainstorm output), CP-AP-3 (only if user proceeds to Phase 2), CP-AP-4 and CP-AP-5 (only if user transitions to produce mode)
 - **Generate project context only** → Enter **Quick Context Mode** (brownfield only):
   - Run Project State Detection → if greenfield, redirect to produce mode
@@ -271,7 +272,7 @@ When the session appears to be ending:
 1. **Remind**: "You set out to produce a project plan but `.prizmkit/plans/project-brief.md` isn't complete yet."
 2. Use `AskUserQuestion`: "How would you like to proceed?"
    - **Continue to completion (Recommended)** — finish the project brief
-   - **Save draft & exit** — write current progress as draft to `.prizmkit/planning/`
+   - **Save draft & exit** — write current progress as draft to `.prizmkit/plans/project-brief.draft.md`
    - **Abandon** — exit without saving
 
 ## Completion Summary
@@ -281,7 +282,7 @@ After all checkpoints pass, present a summary and end the session:
 1. **Summary** (as text): List all project-level artifacts produced:
    - Project conventions → `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Project Conventions`
    - Infrastructure config → `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` (database conventions + deployment config)
-   - Tech stack → `.prizmkit/config.json`
+   - Tech stack assumptions → captured in `.prizmkit/plans/project-brief.md` and reused from `.prizmkit/config.json` when it already exists
    - Architecture decisions (if any) → `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Architecture Decisions`
    - Dev rules (if configured) → `.prizmkit/rules/<layer>-rules.md` (with `root.prizm` `RULES:` pointer)
    - Project brief → `.prizmkit/plans/project-brief.md`

package/bundled/skills/app-planner/references/project-brief-guide.md

@@ -1,6 +1,6 @@
 # Project Brief Template
 
-> Capture the user's key product ideas as a simple checklist. Each line is one idea. This file is referenced by `root.prizm` (`PROJECT_BRIEF:`) so every new AI session automatically knows the project's goals.
+> Capture the user's key product ideas as a simple checklist. Each line is one idea. Downstream planners can load this file as project-level context.
 
 ## File Location
 
@@ -70,7 +70,7 @@ Stop asking when ALL of these are clear:
 2. **Users** — who will use it and in what context
 3. **Core features** — at least 3 concrete capabilities (not vague aspirations)
 4. **Boundaries** — what's in scope vs. out of scope for V1
-5. **Technical direction** — enough to populate `config.json` tech_stack (or explicitly deferred)
+5. **Technical direction** — enough to describe stack assumptions in the brief, or explicitly mark them deferred
 
 If the user gives short/vague answers, don't accept them — rephrase and ask again. A weak brief leads to weak specs downstream.
 

package/bundled/skills/app-planner/references/rules/backend/derivation-rules.md

@@ -614,6 +614,6 @@ This table verifies every template placeholder has at least one derivation rule
 | `{{ ai_dependency_rule }}` | Yes | No | D-AI-DEP-STRICT-01, D-AI-DEP-ANNOUNCE-01, D-AI-DEP-LOOSE-01 |
 | `{{ ai_breaking_change_rule }}` | Yes | No | D-AI-BREAK-STRICT-01, D-AI-BREAK-LOOSE-01 |
 | `{{ ai_config_rule }}` | Yes | No | D-AI-CONFIG-STRICT-01, D-AI-CONFIG-SYNC-01 |
-| `{{ FIXED_RULES_* }}` | No | Yes | `references/fixed-rules.md` |
+| `{{ FIXED_RULES_* }}` | No | Yes | `references/rules/backend/fixed-rules.md` |
 | `{{ deny_list_summary }}` | N/A | N/A | AI auto-generates in Phase 4 |
 | `{{ recommended_libs }}` | N/A | N/A | AI auto-generates in Phase 4 |

package/bundled/skills/app-planner/references/rules/frontend/derivation-rules.md

@@ -2,7 +2,7 @@
 
 > This file defines the mapping "Phase 2 answers → rule blocks auto-injected into frontend-rules.md". The AI reads this file in Phase 3 — **do not ask the user again**.
 >
-> Usage: Each rule block has a unique ID (e.g., `D-TAILWIND-01`). After matching the user's answer, inject the "rule body" verbatim into the corresponding `{{ ... }}` placeholder in [frontend-rules.template.md](../templates/frontend-rules.template.md).
+> Usage: Each rule block has a unique ID (e.g., `D-TAILWIND-01`). After matching the user's answer, inject the "rule body" verbatim into the corresponding `{{ ... }}` placeholder in [`template.md`](template.md).
 
 ---
 

package/bundled/skills/app-planner/references/rules-configuration.md

@@ -1,6 +1,28 @@
-# Rules Configuration — Detailed Q&A Procedures
+# Rules Configuration — Full Procedure
 
-Procedural details for configuring per-layer development rules during app planning. SKILL.md retains Steps 1-3 and 5 (flow control); this file contains Step 4's full Q&A workflow.
+Procedure for configuring per-layer development rules during app planning.
+
+## Step 1: Detect Layers
+
+- Prefer `.prizmkit/config.json` `tech_stack` when present.
+- Otherwise infer layers from project files:
+  - frontend: `package.json` plus React/Vue/Svelte/Next/Vite indicators
+  - backend: Express/FastAPI/Django/Go/Java service indicators
+  - database: migrations, ORM config, schema files, or DB dependencies
+  - mobile: Flutter/React Native/iOS/Android indicators
+- Present detected layers with `AskUserQuestion`; include "Skip rules configuration" as a non-blocking option.
+
+## Step 2: Choose Configuration Mode
+
+- Quick mode asks only manifest groups marked `quick_mode: true`.
+- Full mode asks every manifest group in order.
+- Skip mode records no rules file for that layer and continues without reminders.
+
+## Step 3: Ask Questions with AskUserQuestion
+
+- Convert each question-bank option group into selectable `AskUserQuestion` options.
+- Do not ask users to type letter shortcuts such as `A` or `1`; those shortcuts are legacy notation in question banks only.
+- Every non-essential question includes a skip/defer option.
 
 ## Step 4: Configure Each Selected Layer — Full Q&A Workflow
 
@@ -10,37 +32,42 @@ For each selected layer, run the 4-phase rule generation pattern:
 
 - Read `${SKILL_DIR}/references/rules/<layer>/fixed-rules.md` — industry-consensus rules injected without asking
 - Read `${SKILL_DIR}/references/rules/<layer>/question-bank.md` — interactive questions organized in groups (G1->G10): authoritative source for question text, options, "Recommended" markers, and Notes
-- Read `${SKILL_DIR}/references/rules/<layer>/question-manifest.json` — machine-readable structure for this layer. **This is your asking checklist.** It lists, per question: `group`, `required`, `maps_to` (which template placeholders the answer fills), and conditional fields (`required_if`, `auto_derived_when`, `options_vary_by`). Its `groups[]` carries each group's `quick_mode` flag, and `template_placeholders` is the expected-set for the Phase D self-check. Use the manifest to track coverage; use question-bank.md for the actual wording you present to the user. If a question id in one file is absent from the other, trust question-bank.md for content and note the drift.
+- Read `${SKILL_DIR}/references/rules/<layer>/question-manifest.json` — machine-readable structure for this layer. This is the asking checklist. It lists, per question: `group`, `required`, `maps_to`, `required_if`, `auto_derived_when`, and `options_vary_by`. Its `groups[]` carries each group's `quick_mode` flag, and `template_placeholders` is the expected-set for the Phase D self-check. Use the manifest to track coverage; use question-bank.md for the actual wording you present to the user. If a question id in one file is absent from the other, trust question-bank.md for content and note the drift.
 
 ### Phase B — Interactive Q&A
 
-- Ask questions one group at a time (max 3 questions per message), as defined in question-bank.md
-- Each question shows a "Recommended" option to reduce decision cost
-- **Quick mode**: ask only the groups whose `quick_mode` is `true` in `question-manifest.json`. All other groups adopt recommended defaults silently. (The manifest is the single source of truth for quick-mode membership — do not hardcode group lists here.)
-- **Full mode**: ask all groups in manifest order (`groups[]`).
-- **Conditional questions** (driven by the manifest's per-question fields):
-  - `required_if: "<expr>"` — ask this question only when the expression over prior answers holds (e.g. Q14 `required_if: Q13 != D`). If the condition is false, the question is legitimately skipped — not a coverage gap.
-  - `auto_derived_when: "<expr>"` — when this holds, fill the mapped placeholder(s) from the prior answer without asking (e.g. backend Q6 `auto_derived_when: Q5 in [GraphQL, gRPC]`). Count as satisfied, not skipped.
-  - `options_vary_by: "<Qid>"` — the question is still asked; only its option list depends on that prior answer (e.g. framework/ORM options vary by language). Never affects whether the question is required.
-- Shortcut commands work at any point:
-  - `recommended` / `default` -> adopt all recommended for current group
-  - `all recommended` -> adopt all recommended for all remaining groups
-  - `skip` -> mark current group as "Not required at this stage"
+- Ask questions one group at a time (max 3 questions per message), as defined in question-bank.md.
+- Each question shows a "Recommended" option to reduce decision cost.
+- Quick mode: ask only the groups whose `quick_mode` is `true` in `question-manifest.json`. All other groups adopt recommended defaults silently.
+- Full mode: ask all groups in manifest order (`groups[]`).
+- Conditional questions:
+  - `required_if: "<expr>"` — ask this question only when the expression over prior answers holds. If false, the question is legitimately skipped.
+  - `auto_derived_when: "<expr>"` — when true, fill the mapped placeholder(s) from the prior answer without asking. Count as satisfied, not skipped.
+  - `options_vary_by: "<Qid>"` — the question is still asked; only its option list depends on that prior answer.
+- Legacy shortcut labels in question banks such as `recommended`, `default`, or `skip` are converted into selectable options in `AskUserQuestion`.
+- Do not ask the user to type these commands manually; selectable options prevent merged or missed decisions.
 - Record answers in memory after each group. Track which manifest questions are answered, auto-derived, or conditionally skipped so Phase D can verify coverage.
 
 ### Phase C — Auto-derivation
 
-- Read `${SKILL_DIR}/references/rules/<layer>/derivation-rules.md`
-- Match user answers against the trigger map using keyword matching
-- Derive platform-specific rules without asking the user (e.g., choosing Flutter -> auto-inject Flutter widget/persistence/navigation rules)
+- Read `${SKILL_DIR}/references/rules/<layer>/derivation-rules.md`.
+- Match user answers against the trigger map using keyword matching.
+- Derive platform-specific rules without asking the user.
 
 ### Phase D — Render and Write
 
-- Read `${SKILL_DIR}/references/rules/<layer>/template.md`
-- Fill all template placeholders with accumulated content from Phases A+B+C
-- **Post-render self-check** (driven by `question-manifest.json` -> `template_placeholders`):
-  1. **Coverage pass** — for every placeholder in `from_questions`, confirm it traces to an answered question OR an `auto_derived_when` path OR a conditionally-skipped question (`required_if` false). If a `from_questions` placeholder has no source, you skipped a required question — go back and ask it before writing.
-  2. **Residual pass** — scan the rendered document for any residual `{{ ` or ` }}`; count must be 0. Placeholders in `from_fixed_rules` / `auto_generated` / `metadata` are filled from fixed-rules.md, Phase D generation, and project metadata respectively — they are NOT expected to come from Q&A, but they MUST still be rendered (no residual braces).
-- Generate Appendix A (Deny List) and Appendix B (Recommended Tools) per template instructions — these fill the `auto_generated` placeholders
-- Create `.prizmkit/rules/` directory if it doesn't exist
-- Write `.prizmkit/rules/<layer>-rules.md`
+- Read `${SKILL_DIR}/references/rules/<layer>/template.md`.
+- Fill all template placeholders with accumulated content from Phases A+B+C.
+- Post-render self-check driven by `question-manifest.json` -> `template_placeholders`:
+  1. Coverage pass — for every placeholder in `from_questions`, confirm it traces to an answered question OR an `auto_derived_when` path OR a conditionally-skipped question (`required_if` false). If a `from_questions` placeholder has no source, go back and ask it before writing.
+  2. Residual pass — scan the rendered document for any residual `{{ ` or ` }}`; count must be 0. Placeholders in `from_fixed_rules`, `auto_generated`, and `metadata` are filled from fixed rules, Phase D generation, and project metadata.
+- Generate Appendix A (Deny List) and Appendix B (Recommended Tools) per template instructions.
+- Create `.prizmkit/rules/` directory if it doesn't exist.
+- Write `.prizmkit/rules/<layer>-rules.md`.
+
+## Step 5: Update root.prizm RULES Pointer
+
+- Ensure `.prizmkit/prizm-docs/root.prizm` has a concise `RULES:` pointer to configured rules.
+- If root.prizm exists, update only the `RULES:` line.
+- If root.prizm is absent, create a minimal valid root.prizm with required fields and a `RULES:` pointer.
+- Do not write architecture decisions, project brief content, or changelog metadata into root.prizm.