prizmkit 1.1.20 → 1.1.23

package/bundled/dev-pipeline/scripts/update-feature-status.py

@@ -153,24 +153,20 @@ def now_iso():
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
-def load_feature_status(state_dir, feature_id, feature_list_status=None):
-    """Load the status.json for a feature.
+def load_feature_status(state_dir, feature_id):
+    """Load the runtime state from status.json for a feature.
 
-    If the file does not exist, return a default pending status.
-
-    If feature_list_status is a terminal status (completed, failed, skipped),
-    it overrides the status field from status.json. This makes .prizmkit/plans/feature-list.json
-    the single source of truth for terminal statuses, while all other fields
-    (retry_count, sessions, etc.) still come from status.json.
+    Returns runtime fields only (retry_count, sessions, etc.).
+    The 'status' field is NOT included — status lives exclusively
+    in feature-list.json.
     """
     status_path = os.path.join(
         state_dir, "features", feature_id, "status.json"
     )
     if not os.path.isfile(status_path):
         now = now_iso()
-        data = {
+        return {
             "feature_id": feature_id,
-            "status": feature_list_status if feature_list_status else "pending",
             "retry_count": 0,
             "max_retries": 3,
             "sessions": [],
@@ -179,14 +175,11 @@ def load_feature_status(state_dir, feature_id, feature_list_status=None):
             "created_at": now,
             "updated_at": now,
         }
-        return data
     data, err = load_json_file(status_path)
     if err:
-        # If we can't read it, treat as pending
         now = now_iso()
-        data = {
+        return {
             "feature_id": feature_id,
-            "status": feature_list_status if feature_list_status else "pending",
             "retry_count": 0,
             "max_retries": 3,
             "sessions": [],
@@ -195,20 +188,32 @@ def load_feature_status(state_dir, feature_id, feature_list_status=None):
             "created_at": now,
             "updated_at": now,
         }
-    # .prizmkit/plans/feature-list.json wins for terminal statuses
-    if feature_list_status in TERMINAL_STATUSES:
-        data["status"] = feature_list_status
+    # Defensively remove status if present (legacy data)
+    data.pop("status", None)
     return data
 
 
 def save_feature_status(state_dir, feature_id, status_data):
-    """Write the status.json for a feature."""
+    """Write the status.json for a feature (runtime fields only)."""
+    # Defensively strip status — it belongs in feature-list.json
+    status_data.pop("status", None)
     status_path = os.path.join(
         state_dir, "features", feature_id, "status.json"
     )
     return write_json_file(status_path, status_data)
 
 
+def get_feature_status_from_list(feature_list_path, feature_id):
+    """Read a single feature's status from feature-list.json."""
+    data, err = load_json_file(feature_list_path)
+    if err:
+        return "pending"
+    for f in data.get("features", []):
+        if isinstance(f, dict) and f.get("id") == feature_id:
+            return f.get("status", "pending")
+    return "pending"
+
+
 def update_feature_in_list(feature_list_path, feature_id, new_status):
     """Update a feature's status field in .prizmkit/plans/feature-list.json.
 
@@ -389,10 +394,9 @@ def auto_skip_blocked_features(feature_list_path, state_dir, failed_feature_id):
             f["status"] = "auto_skipped"
     write_json_file(feature_list_path, data)
 
-    # Sync status.json for each auto-skipped feature
+    # Update timestamps in status.json for each auto-skipped feature
     for fid in to_skip:
         fs = load_feature_status(state_dir, fid)
-        fs["status"] = "auto_skipped"
         fs["updated_at"] = now_iso()
         save_feature_status(state_dir, fid, fs)
 
@@ -454,18 +458,19 @@ def action_get_next(feature_list_data, state_dir, feature_filter=None):
         return
 
     # Build status map from ALL features (for dependency checking).
+    # Status comes from feature-list.json (the single source of truth).
     # This must happen BEFORE the feature filter is applied, because
     # filtered features may depend on features outside the filter.
     status_map = {}  # feature_id -> status string
-    status_data_map = {}  # feature_id -> full status data
+    status_data_map = {}  # feature_id -> runtime status data (retry_count, etc.)
     for feature in features:
         if not isinstance(feature, dict):
             continue
         fid = feature.get("id")
         if not fid:
             continue
-        fs = load_feature_status(state_dir, fid, feature.get("status"))
-        status_map[fid] = fs.get("status", "pending")
+        status_map[fid] = feature.get("status", "pending")
+        fs = load_feature_status(state_dir, fid)
         status_data_map[fid] = fs
 
     # Apply feature filter: only consider these features as candidates
@@ -576,12 +581,16 @@ def action_update(args, feature_list_path, state_dir):
         return
 
     fs = load_feature_status(state_dir, feature_id)
+    current_list_status = get_feature_status_from_list(feature_list_path, feature_id)
+
+    # Track what status we write to feature-list.json
+    new_status = current_list_status
 
     if session_status == "success":
         # No-op guard: if this exact successful session was already recorded,
         # avoid rewriting state files again (prevents post-commit dirty changes).
         existing_sessions = fs.get("sessions", [])
-        already_completed = fs.get("status") == "completed" and fs.get("resume_from_phase") is None
+        already_completed = current_list_status == "completed" and fs.get("resume_from_phase") is None
         same_session_already_recorded = (
             session_id
             and session_id in existing_sessions
@@ -592,7 +601,7 @@ def action_update(args, feature_list_path, state_dir):
                 "action": "update",
                 "feature_id": feature_id,
                 "session_status": session_status,
-                "new_status": fs.get("status", "completed"),
+                "new_status": "completed",
                 "retry_count": fs.get("retry_count", 0),
                 "resume_from_phase": fs.get("resume_from_phase"),
                 "updated_at": fs.get("updated_at"),
@@ -601,7 +610,7 @@ def action_update(args, feature_list_path, state_dir):
             print(json.dumps(summary, indent=2, ensure_ascii=False))
             return
 
-        fs["status"] = "completed"
+        new_status = "completed"
         fs["resume_from_phase"] = None
         err = update_feature_in_list(feature_list_path, feature_id, "completed")
         if err:
@@ -614,42 +623,33 @@ def action_update(args, feature_list_path, state_dir):
         fs["retry_count"] = fs.get("retry_count", 0) + 1
 
         if fs["retry_count"] >= max_retries:
-            fs["status"] = "failed"
-            target_status = "failed"
+            new_status = "failed"
         else:
-            # status.json keeps the granular degraded reason for diagnostics
-            fs["status"] = session_status
             # feature-list.json gets schema-valid "pending" (will be retried)
-            target_status = "pending"
+            new_status = "pending"
 
         fs["degraded_reason"] = session_status
         fs["resume_from_phase"] = None
         fs["sessions"] = []
         fs["last_session_id"] = None
 
-        err = update_feature_in_list(feature_list_path, feature_id, target_status)
+        err = update_feature_in_list(feature_list_path, feature_id, new_status)
         if err:
             error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
             return
     else:
         # crashed / failed / timed_out — preserve all artifacts for debugging.
-        # Previous behavior deleted everything via cleanup_feature_artifacts(),
-        # making it impossible to diagnose why the session failed.
         fs["retry_count"] = fs.get("retry_count", 0) + 1
 
         if fs["retry_count"] >= max_retries:
-            fs["status"] = "failed"
-            target_status = "failed"
+            new_status = "failed"
         else:
-            fs["status"] = "pending"
-            target_status = "pending"
+            new_status = "pending"
 
         fs["resume_from_phase"] = None
         # Keep sessions list and last_session_id for debugging
-        # fs["sessions"] = []
-        # fs["last_session_id"] = None
 
-        err = update_feature_in_list(feature_list_path, feature_id, target_status)
+        err = update_feature_in_list(feature_list_path, feature_id, new_status)
         if err:
             error_out("Failed to update .prizmkit/plans/feature-list.json: {}".format(err))
             return
@@ -670,7 +670,7 @@ def action_update(args, feature_list_path, state_dir):
 
     # Auto-skip downstream features when this feature is marked as failed or skipped
     auto_skipped_features = []
-    if fs["status"] in ("failed", "skipped"):
+    if new_status in ("failed", "skipped"):
         auto_skipped_features = auto_skip_blocked_features(
             feature_list_path, state_dir, feature_id
         )
@@ -679,7 +679,7 @@ def action_update(args, feature_list_path, state_dir):
         "action": "update",
         "feature_id": feature_id,
         "session_status": session_status,
-        "new_status": fs["status"],
+        "new_status": new_status,
         "retry_count": fs["retry_count"],
         "resume_from_phase": fs.get("resume_from_phase"),
         "updated_at": fs["updated_at"],
@@ -776,12 +776,12 @@ def _estimate_remaining_time(features, state_dir, counts, feature_list_data=None
     # Complexity weights (used for estimation when no historical data is available)
     COMPLEXITY_WEIGHT = {"low": 1.0, "medium": 2.0, "high": 4.0}
 
-    # Build feature-list status map for terminal status override
+    # Build feature-list status map (status lives in feature-list.json)
     fl_status_map = {}
     if feature_list_data:
         for f in feature_list_data.get("features", []):
             if isinstance(f, dict) and f.get("id"):
-                fl_status_map[f["id"]] = f.get("status")
+                fl_status_map[f["id"]] = f.get("status", "pending")
 
     # Collect completed feature durations grouped by complexity
     duration_by_complexity = {}  # complexity -> [duration_seconds]
@@ -803,8 +803,7 @@ def _estimate_remaining_time(features, state_dir, counts, feature_list_data=None
         fid = feature.get("id")
         if not fid:
             continue
-        fs = load_feature_status(state_dir, fid, fl_status_map.get(fid))
-        if fs.get("status") != "completed":
+        if fl_status_map.get(fid) != "completed":
             continue
         duration = _calc_feature_duration(state_dir, fid)
         if duration is None:
@@ -833,8 +832,7 @@ def _estimate_remaining_time(features, state_dir, counts, feature_list_data=None
         fid = feature.get("id")
         if not fid:
             continue
-        fs = load_feature_status(state_dir, fid, fl_status_map.get(fid))
-        fstatus = fs.get("status", "pending")
+        fstatus = fl_status_map.get(fid, "pending")
         if fstatus in TERMINAL_STATUSES:
             continue
         remaining_count += 1
@@ -910,7 +908,7 @@ def action_status(feature_list_data, state_dir, feature_filter=None):
         fid = feature.get("id")
         if not fid:
             continue
-        fs = load_feature_status(state_dir, fid, feature.get("status"))
+        fs = load_feature_status(state_dir, fid)
         dr = fs.get("degraded_reason")
         if dr:
             degraded_reason_map[fid] = dr
@@ -1089,9 +1087,8 @@ def action_start(args, feature_list_path, state_dir):
         return
 
     fs = load_feature_status(state_dir, feature_id)
-    old_status = fs.get("status", "pending")
+    old_status = get_feature_status_from_list(feature_list_path, feature_id)
 
-    fs["status"] = "in_progress"
     fs["updated_at"] = now_iso()
 
     err = save_feature_status(state_dir, feature_id, fs)
@@ -1121,7 +1118,7 @@ def action_start(args, feature_list_path, state_dir):
 def action_reset(args, feature_list_path, state_dir):
     """Reset a feature to pending state.
 
-    Resets status.json (status -> pending, retry_count -> 0, clear sessions,
+    Resets status.json runtime fields (retry_count -> 0, clear sessions,
     clear resume_from_phase) and updates .prizmkit/plans/feature-list.json status to pending.
     Does NOT delete any files on disk.
     """
@@ -1132,11 +1129,10 @@ def action_reset(args, feature_list_path, state_dir):
 
     # Load current status to preserve created_at
     fs = load_feature_status(state_dir, feature_id)
-    old_status = fs.get("status", "unknown")
+    old_status = get_feature_status_from_list(feature_list_path, feature_id)
     old_retry = fs.get("retry_count", 0)
 
-    # Reset fields
-    fs["status"] = "pending"
+    # Reset runtime fields
     fs["retry_count"] = 0
     fs["sessions"] = []
     fs["last_session_id"] = None
@@ -1227,10 +1223,9 @@ def action_clean(args, feature_list_path, state_dir):
 
     # 5. Reset status (reuse reset logic)
     fs = load_feature_status(state_dir, feature_id)
-    old_status = fs.get("status", "unknown")
+    old_status = get_feature_status_from_list(feature_list_path, feature_id)
     old_retry = fs.get("retry_count", 0)
 
-    fs["status"] = "pending"
     fs["retry_count"] = 0
     fs["sessions"] = []
     fs["last_session_id"] = None
@@ -1387,10 +1382,9 @@ def action_unskip(args, feature_list_path, state_dir):
         error_out("Failed to write .prizmkit/plans/feature-list.json: {}".format(err))
         return
 
-    # Reset status.json for each feature
+    # Reset runtime fields in status.json for each feature
     for fid in to_reset:
         fs = load_feature_status(state_dir, fid)
-        fs["status"] = "pending"
         fs["retry_count"] = 0
         fs["sessions"] = []
         fs["last_session_id"] = None

package/bundled/dev-pipeline/scripts/update-refactor-status.py

@@ -96,11 +96,10 @@ def now_iso():
 
 
 def _default_status(refactor_id):
-    """Create a default refactor status object."""
+    """Create a default refactor runtime status object (no status field)."""
     now = now_iso()
     return {
         "refactor_id": refactor_id,
-        "status": "pending",
         "retry_count": 0,
         "max_retries": 3,
         "sessions": [],
@@ -112,20 +111,42 @@ def _default_status(refactor_id):
 
 
 def load_refactor_status(state_dir, refactor_id):
+    """Load runtime state from status.json for a refactor.
+
+    Returns runtime fields only (retry_count, sessions, etc.).
+    The 'status' field is NOT included — status lives exclusively
+    in refactor-list.json.
+    """
     status_path = os.path.join(state_dir, "refactors", refactor_id, "status.json")
     if not os.path.isfile(status_path):
         return _default_status(refactor_id)
     data, err = load_json_file(status_path)
     if err:
         return _default_status(refactor_id)
+    # Defensively remove status if present (legacy data)
+    data.pop("status", None)
     return data
 
 
 def save_refactor_status(state_dir, refactor_id, status_data):
+    """Write the status.json for a refactor (runtime fields only)."""
+    # Defensively strip status — it belongs in refactor-list.json
+    status_data.pop("status", None)
     status_path = os.path.join(state_dir, "refactors", refactor_id, "status.json")
     return write_json_file(status_path, status_data)
 
 
+def get_refactor_status_from_list(refactor_list_path, refactor_id):
+    """Read a single refactor's status from refactor-list.json."""
+    data, err = load_json_file(refactor_list_path)
+    if err:
+        return "pending"
+    for r in data.get("refactors", []):
+        if isinstance(r, dict) and r.get("id") == refactor_id:
+            return r.get("status", "pending")
+    return "pending"
+
+
 def update_refactor_in_list(refactor_list_path, refactor_id, new_status):
     data, err = load_json_file(refactor_list_path)
     if err:
@@ -179,7 +200,7 @@ def action_get_next(refactor_list_data, state_dir):
         print("PIPELINE_COMPLETE")
         return
 
-    # Build status map and completed set
+    # Build status map from refactor-list.json (single source of truth)
     status_map = {}
     status_data_map = {}
     for r in refactors:
@@ -188,8 +209,8 @@ def action_get_next(refactor_list_data, state_dir):
         rid = r.get("id")
         if not rid:
             continue
+        status_map[rid] = r.get("status", "pending")
         rs = load_refactor_status(state_dir, rid)
-        status_map[rid] = rs.get("status", "pending")
         status_data_map[rid] = rs
 
     completed_set = {rid for rid, st in status_map.items() if st in TERMINAL_STATUSES}
@@ -270,35 +291,30 @@ def action_update(args, refactor_list_path, state_dir):
 
     rs = load_refactor_status(state_dir, refactor_id)
 
+    # Track what status we write to refactor-list.json
+    new_status = get_refactor_status_from_list(refactor_list_path, refactor_id)
+
     if session_status == "success":
-        rs["status"] = "completed"
+        new_status = "completed"
         rs["resume_from_phase"] = None
         err = update_refactor_in_list(refactor_list_path, refactor_id, "completed")
         if err:
             error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
             return
     elif session_status in ("commit_missing", "docs_missing", "merge_conflict"):
-        # Degraded outcome: keep artifacts for retry.
-        # Write schema-valid status to refactor-list.json ("pending" for retry,
-        # "failed" if max retries exceeded). Store the granular degraded reason
-        # in status.json only (internal pipeline state, not schema-bound).
         rs["retry_count"] = rs.get("retry_count", 0) + 1
 
         if rs["retry_count"] >= max_retries:
-            rs["status"] = "failed"
-            target_status = "failed"
+            new_status = "failed"
         else:
-            # status.json keeps the granular degraded reason for diagnostics
-            rs["status"] = session_status
-            # refactor-list.json gets schema-valid "pending" (will be retried)
-            target_status = "pending"
+            new_status = "pending"
 
         rs["degraded_reason"] = session_status
         rs["resume_from_phase"] = None
         rs["sessions"] = []
         rs["last_session_id"] = None
 
-        err = update_refactor_in_list(refactor_list_path, refactor_id, target_status)
+        err = update_refactor_in_list(refactor_list_path, refactor_id, new_status)
         if err:
             error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
             return
@@ -312,17 +328,15 @@ def action_update(args, refactor_list_path, state_dir):
         )
 
         if rs["retry_count"] >= max_retries:
-            rs["status"] = "failed"
-            target_status = "failed"
+            new_status = "failed"
         else:
-            rs["status"] = "pending"
-            target_status = "pending"
+            new_status = "pending"
 
         rs["resume_from_phase"] = None
         rs["sessions"] = []
         rs["last_session_id"] = None
 
-        err = update_refactor_in_list(refactor_list_path, refactor_id, target_status)
+        err = update_refactor_in_list(refactor_list_path, refactor_id, new_status)
         if err:
             error_out("Failed to update .prizmkit/plans/refactor-list.json: {}".format(err))
             return
@@ -343,7 +357,7 @@ def action_update(args, refactor_list_path, state_dir):
 
     # Auto-skip downstream refactors when this refactor is marked as failed or skipped
     auto_skipped_refactors = []
-    if rs["status"] in ("failed", "skipped"):
+    if new_status in ("failed", "skipped"):
         auto_skipped_refactors = auto_skip_blocked_refactors(
             refactor_list_path, state_dir, refactor_id
         )
@@ -352,7 +366,7 @@ def action_update(args, refactor_list_path, state_dir):
         "action": "update",
         "refactor_id": refactor_id,
         "session_status": session_status,
-        "new_status": rs["status"],
+        "new_status": new_status,
         "retry_count": rs["retry_count"],
         "resume_from_phase": rs.get("resume_from_phase"),
         "updated_at": rs["updated_at"],
@@ -496,10 +510,9 @@ def auto_skip_blocked_refactors(refactor_list_path, state_dir, failed_refactor_i
             r["status"] = "auto_skipped"
     write_json_file(refactor_list_path, data)
 
-    # Sync status.json for each auto-skipped refactor
+    # Update timestamps in status.json for each auto-skipped refactor
     for rid in to_skip:
         rs = load_refactor_status(state_dir, rid)
-        rs["status"] = "auto_skipped"
         rs["updated_at"] = now_iso()
         save_refactor_status(state_dir, rid, rs)
 
@@ -589,8 +602,8 @@ def action_status(refactor_list_data, state_dir):
         if not rid:
             continue
 
+        rstatus = r.get("status", "pending")
         rs = load_refactor_status(state_dir, rid)
-        rstatus = rs.get("status", "pending")
         retry_count = rs.get("retry_count", 0)
         max_retries_val = rs.get("max_retries", 3)
         resume_phase = rs.get("resume_from_phase")
@@ -688,10 +701,9 @@ def action_reset(args, refactor_list_path, state_dir):
         return
 
     rs = load_refactor_status(state_dir, refactor_id)
-    old_status = rs.get("status", "unknown")
+    old_status = get_refactor_status_from_list(refactor_list_path, refactor_id)
     old_retry = rs.get("retry_count", 0)
 
-    rs["status"] = "pending"
     rs["retry_count"] = 0
     rs["sessions"] = []
     rs["last_session_id"] = None
@@ -760,10 +772,9 @@ def action_clean(args, refactor_list_path, state_dir):
 
     # 4. Reset status
     rs = load_refactor_status(state_dir, refactor_id)
-    old_status = rs.get("status", "unknown")
+    old_status = get_refactor_status_from_list(refactor_list_path, refactor_id)
     old_retry = rs.get("retry_count", 0)
 
-    rs["status"] = "pending"
     rs["retry_count"] = 0
     rs["sessions"] = []
     rs["last_session_id"] = None
@@ -834,9 +845,8 @@ def action_start(args, refactor_list_path, state_dir):
         return
 
     rs = load_refactor_status(state_dir, refactor_id)
-    old_status = rs.get("status", "pending")
+    old_status = get_refactor_status_from_list(refactor_list_path, refactor_id)
 
-    rs["status"] = "in_progress"
     rs["updated_at"] = now_iso()
 
     err = save_refactor_status(state_dir, refactor_id, rs)
@@ -988,10 +998,9 @@ def action_unskip(args, refactor_list_path, state_dir):
         error_out("Failed to write .prizmkit/plans/refactor-list.json: {}".format(err))
         return
 
-    # Reset status.json for each refactor
+    # Reset runtime fields in status.json for each refactor
     for rid in to_reset:
         rs = load_refactor_status(state_dir, rid)
-        rs["status"] = "pending"
         rs["retry_count"] = 0
         rs["sessions"] = []
         rs["last_session_id"] = None

package/bundled/dev-pipeline/templates/bootstrap-tier1.md

@@ -194,17 +194,32 @@ You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without
 You know this project's tech stack. Detect and start the dev server yourself:
 
 1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
-2. Choose an available port — check what the project defaults to, or pick one that is free:
+2. **Detect the dev server port** — use the pre-detected port from pipeline if available, otherwise extract from project config. Do NOT hardcode or guess the port:
    ```bash
-   lsof -ti:<port> 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   # Use pipeline-injected port if available, otherwise extract from package.json
+   DEV_PORT={{DEV_PORT}}
+   # If DEV_PORT is still a placeholder, detect at runtime:
+   if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
+     DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')")
+     if [ -z "$DEV_PORT" ]; then
+       DEV_PORT=$(echo "$NEXT_PUBLIC_SITE_URL" | sed -nE 's|.*:([0-9]+).*|\1|p')
+     fi
+     DEV_PORT=${DEV_PORT:-3000}
+   fi
+   echo "Detected DEV_PORT=$DEV_PORT"
    ```
-3. Start the dev server in background, capture PID:
+3. Verify the port is available:
+   ```bash
+   lsof -ti:$DEV_PORT 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   ```
+4. Start the dev server in background, capture PID:
    ```bash
    <start-command> &
    DEV_SERVER_PID=$!
    ```
-4. Wait for server to be ready: poll the target URL with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-5. If the page requires authentication, use playwright-cli to register a test user and log in first
+5. Wait for server to be ready: poll `http://localhost:$DEV_PORT` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
+7. If the page requires authentication, use playwright-cli to register a test user and log in first
 
 **Step 2 — Verification**:
 
@@ -217,14 +232,14 @@ Take a final screenshot for evidence.
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
 1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-2. Verify port is released: `lsof -ti:<port> | xargs kill -9 2>/dev/null || true`
+2. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
 
 **Step 4 — Reporting**:
 
 Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
-   URL: <actual URL used>
+   URL: http://localhost:$DEV_PORT
    Dev Server Command: <actual command used>
    Steps executed: [list]
    Screenshot: [path]

package/bundled/dev-pipeline/templates/bootstrap-tier2.md

@@ -292,17 +292,32 @@ You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without
 You know this project's tech stack. Detect and start the dev server yourself:
 
 1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
-2. Choose an available port — check what the project defaults to, or pick one that is free:
+2. **Detect the dev server port** — use the pre-detected port from pipeline if available, otherwise extract from project config. Do NOT hardcode or guess the port:
    ```bash
-   lsof -ti:<port> 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   # Use pipeline-injected port if available, otherwise extract from package.json
+   DEV_PORT={{DEV_PORT}}
+   # If DEV_PORT is still a placeholder, detect at runtime:
+   if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
+     DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')")
+     if [ -z "$DEV_PORT" ]; then
+       DEV_PORT=$(echo "$NEXT_PUBLIC_SITE_URL" | sed -nE 's|.*:([0-9]+).*|\1|p')
+     fi
+     DEV_PORT=${DEV_PORT:-3000}
+   fi
+   echo "Detected DEV_PORT=$DEV_PORT"
    ```
-3. Start the dev server in background, capture PID:
+3. Verify the port is available:
+   ```bash
+   lsof -ti:$DEV_PORT 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   ```
+4. Start the dev server in background, capture PID:
    ```bash
    <start-command> &
    DEV_SERVER_PID=$!
    ```
-4. Wait for server to be ready: poll the target URL with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-5. If the page requires authentication, use playwright-cli to register a test user and log in first
+5. Wait for server to be ready: poll `http://localhost:$DEV_PORT` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
+7. If the page requires authentication, use playwright-cli to register a test user and log in first
 
 **Step 2 — Verification**:
 
@@ -315,14 +330,14 @@ Take a final screenshot for evidence.
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
 1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-2. Verify port is released: `lsof -ti:<port> | xargs kill -9 2>/dev/null || true`
+2. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
 
 **Step 4 — Reporting**:
 
 Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
-   URL: <actual URL used>
+   URL: http://localhost:$DEV_PORT
    Dev Server Command: <actual command used>
    Steps executed: [list]
    Screenshot: [path]