@raquezha/norpiv 0.0.2

package/scripts/validate_active_task.sh

@@ -0,0 +1,328 @@
+#!/usr/bin/env bash
+
+# validate_active_task.sh
+# Lightweight, print-only validation of .workflow/active_task.json and related files.
+# This script never mutates task state; it only reports inconsistencies and suggested fixes.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TRIAGE_HELPER="$SCRIPT_DIR/triage_helper.sh"
+REPO_ROOT=$(git rev-parse --show-toplevel)
+ATF="$REPO_ROOT/.workflow/active_task.json"
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || true)
+WORK_MD=""
+TASK_DIR=""
+META=""
+WARNINGS=0
+ERRORS=0
+
+warn() {
+  WARNINGS=$((WARNINGS + 1))
+  echo "WARN: $*"
+}
+
+error() {
+  ERRORS=$((ERRORS + 1))
+  echo "ERROR: $*"
+}
+
+ok() {
+  echo "OK: $*"
+}
+
+json_read() {
+  local file="$1"
+  local expr="$2"
+  if [[ ! -f "$file" ]]; then
+    echo ""
+    return
+  fi
+  python3 - "$file" "$expr" <<'PY'
+import json
+import re
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+expr = sys.argv[2]
+try:
+    data = json.loads(path.read_text())
+except Exception:
+    print("")
+    raise SystemExit
+
+# Supports the tiny subset used by this validator:
+# .field and .field // .fallback // empty
+for part in [p.strip() for p in expr.split("//")]:
+    if part == "empty":
+        continue
+    match = re.fullmatch(r"\.([A-Za-z_][A-Za-z0-9_]*)", part)
+    if not match or not isinstance(data, dict):
+        continue
+    value = data.get(match.group(1))
+    if value not in (None, ""):
+        print(value)
+        raise SystemExit
+print("")
+PY
+}
+
+json_pretty() {
+  local file="$1"
+  python3 -m json.tool "$file"
+}
+
+count_section() {
+  local section="$1"
+  local file="$2"
+  grep -Ec "^(## )?\[$section\][[:space:]]*$" "$file" 2>/dev/null || true
+}
+
+section_body_nonempty() {
+  local section="$1"
+  local file="$2"
+  python3 - "$file" "$section" <<'PY'
+import re
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+section = sys.argv[2]
+text = path.read_text() if path.exists() else ""
+lines = text.splitlines()
+header = re.compile(rf"^(## )?\[{re.escape(section)}\]\s*$")
+any_header = re.compile(r"^(## )?\[[A-Z0-9_-]+\]\s*$")
+start = next((i for i, line in enumerate(lines) if header.match(line)), None)
+if start is None:
+    print("no")
+    raise SystemExit
+end = len(lines)
+for i in range(start + 1, len(lines)):
+    if any_header.match(lines[i]):
+        end = i
+        break
+body = "\n".join(lines[start + 1:end]).strip()
+meaningful = [line.strip() for line in body.splitlines() if line.strip() and line.strip() not in {"-", "- [ ]"}]
+print("yes" if meaningful else "no")
+PY
+}
+
+has_plan_checkbox() {
+  local file="$1"
+  python3 - "$file" <<'PY'
+import re
+import sys
+from pathlib import Path
+
+path = Path(sys.argv[1])
+text = path.read_text() if path.exists() else ""
+lines = text.splitlines()
+header = re.compile(r"^(## )?\[PLAN\]\s*$")
+any_header = re.compile(r"^(## )?\[[A-Z0-9_-]+\]\s*$")
+start = next((i for i, line in enumerate(lines) if header.match(line)), None)
+if start is None:
+    print("no")
+    raise SystemExit
+end = len(lines)
+for i in range(start + 1, len(lines)):
+    if any_header.match(lines[i]):
+        end = i
+        break
+body = "\n".join(lines[start + 1:end])
+print("yes" if re.search(r"- \[[ xX]\]", body) else "no")
+PY
+}
+
+print_json_field_report() {
+  local label="$1"
+  local file="$2"
+  shift 2
+
+  echo
+  echo "$label field check:"
+  for field in "$@"; do
+    local value
+    value=$(json_read "$file" ".$field")
+    if [[ -n "$value" ]]; then
+      ok "$field=$value"
+    else
+      warn "$label missing .$field"
+    fi
+  done
+}
+
+if [[ ! -f "$ATF" ]]; then
+  error "No active_task.json found at $ATF"
+  echo "Suggested fixes (dry):"
+  echo "  - Run: $TRIAGE_HELPER <source> <id>"
+  exit 1
+fi
+
+if ! python3 -m json.tool "$ATF" >/dev/null 2>&1; then
+  error "active_task.json is not valid JSON: $ATF"
+  exit 1
+fi
+
+echo "Active task file: $ATF"
+json_pretty "$ATF" || true
+
+TASK_PATH=$(json_read "$ATF" '.taskPath // .path')
+TASK_SOURCE=$(json_read "$ATF" '.source')
+TASK_ID=$(json_read "$ATF" '.sourceId // .id')
+ACTIVE_TASK=$(json_read "$ATF" '.active_task')
+POINTER_BRANCH=$(json_read "$ATF" '.branch')
+
+print_json_field_report "active_task.json" "$ATF" active_task source id sourceId taskPath path branch
+
+echo
+if [[ -n "$TASK_PATH" ]]; then
+  if [[ "$TASK_PATH" = /* ]]; then
+    WORK_MD="$TASK_PATH/WORK.md"
+  else
+    WORK_MD="$REPO_ROOT/$TASK_PATH/WORK.md"
+  fi
+  echo "Using taskPath -> checking: $WORK_MD"
+elif [[ -n "$TASK_ID" ]]; then
+  echo "No taskPath in active_task.json; attempting to derive from source+id"
+  if [[ -n "$TASK_SOURCE" ]]; then
+    TASK_FOLDER="$TASK_SOURCE-$TASK_ID"
+  else
+    TASK_FOLDER="$TASK_ID"
+  fi
+  WORK_MD="$REPO_ROOT/.workflow/tasks/$TASK_FOLDER/WORK.md"
+  echo "Derived path: $WORK_MD"
+else
+  error "Neither taskPath/path nor sourceId/id present in active_task.json"
+fi
+
+if [[ -n "$WORK_MD" && -f "$WORK_MD" ]]; then
+  ok "WORK.md exists at $WORK_MD"
+  TASK_DIR=$(dirname "$WORK_MD")
+  META="$TASK_DIR/metadata.json"
+else
+  error "WORK.md not found at ${WORK_MD:-<unknown>}"
+fi
+
+if [[ -n "$ACTIVE_TASK" && -n "$TASK_DIR" ]]; then
+  ACTUAL_TASK_FOLDER=$(basename "$TASK_DIR")
+  if [[ "$ACTIVE_TASK" == "$ACTUAL_TASK_FOLDER" ]]; then
+    ok "active_task matches task folder ($ACTIVE_TASK)"
+  else
+    warn "active_task ($ACTIVE_TASK) differs from task folder ($ACTUAL_TASK_FOLDER)"
+  fi
+fi
+
+if [[ -n "$CURRENT_BRANCH" && -n "$POINTER_BRANCH" ]]; then
+  if [[ "$CURRENT_BRANCH" == "$POINTER_BRANCH" ]]; then
+    ok "current branch matches active pointer ($CURRENT_BRANCH)"
+  else
+    warn "current branch ($CURRENT_BRANCH) differs from active pointer branch ($POINTER_BRANCH)"
+  fi
+fi
+
+META_ID=""
+META_SOURCE=""
+META_TASK_FOLDER=""
+META_STATUS=""
+META_PHASE=""
+META_BRANCH=""
+
+if [[ -n "$META" ]]; then
+  if [[ -f "$META" ]]; then
+    if python3 -m json.tool "$META" >/dev/null 2>&1; then
+      echo
+      echo "Metadata file: $META"
+      json_pretty "$META" || true
+      print_json_field_report "metadata.json" "$META" id source taskFolder status phase branch createdAt updatedAt
+
+      META_ID=$(json_read "$META" '.id')
+      META_SOURCE=$(json_read "$META" '.source')
+      META_TASK_FOLDER=$(json_read "$META" '.taskFolder')
+      META_STATUS=$(json_read "$META" '.status')
+      META_PHASE=$(json_read "$META" '.phase')
+      META_BRANCH=$(json_read "$META" '.branch')
+
+      if [[ -n "$META_ID" && -n "$TASK_ID" && "$META_ID" != "$TASK_ID" ]]; then
+        warn "metadata.id ($META_ID) differs from active_task id/sourceId ($TASK_ID)"
+      fi
+      if [[ -n "$META_SOURCE" && -n "$TASK_SOURCE" && "$META_SOURCE" != "$TASK_SOURCE" ]]; then
+        warn "metadata.source ($META_SOURCE) differs from active_task.source ($TASK_SOURCE)"
+      fi
+      if [[ -n "$META_TASK_FOLDER" && -n "$TASK_DIR" && "$META_TASK_FOLDER" != "$(basename "$TASK_DIR")" ]]; then
+        warn "metadata.taskFolder ($META_TASK_FOLDER) differs from task folder ($(basename "$TASK_DIR"))"
+      fi
+      if [[ -n "$CURRENT_BRANCH" && -n "$META_BRANCH" && "$CURRENT_BRANCH" != "$META_BRANCH" ]]; then
+        warn "current branch ($CURRENT_BRANCH) differs from metadata.branch ($META_BRANCH)"
+      fi
+    else
+      error "metadata.json is not valid JSON: $META"
+    fi
+  else
+    warn "metadata.json not found at $META"
+  fi
+fi
+
+if [[ -n "$WORK_MD" && -f "$WORK_MD" ]]; then
+  echo
+  echo "WORK.md section health:"
+  for section in BRIEF GRILL PLAN LOG META; do
+    count=$(count_section "$section" "$WORK_MD")
+    case "$count" in
+      0) warn "missing [$section] section" ;;
+      1) ok "[$section] section present once" ;;
+      *) warn "duplicate [$section] sections found ($count)" ;;
+    esac
+  done
+
+  if [[ "$META_PHASE" =~ ^(planned|implementing|verifying|synced|closed)$ ]]; then
+    if [[ "$(has_plan_checkbox "$WORK_MD")" == "yes" ]]; then
+      ok "[PLAN] contains checkboxes for phase=$META_PHASE"
+    else
+      warn "phase=$META_PHASE but [PLAN] has no checkboxes"
+    fi
+  fi
+
+  if [[ "$META_PHASE" == "triaged" && "$(section_body_nonempty "BRIEF" "$WORK_MD")" == "yes" ]]; then
+    warn "phase=triaged but [BRIEF] appears populated; consider updating phase metadata"
+  fi
+fi
+
+if [[ "$META_STATUS" =~ ^(done|archived)$ ]]; then
+  warn "active pointer references a task with status=$META_STATUS; consider cleanup, archive handling, or reopening intentionally"
+fi
+
+echo
+echo "Suggested fixes (dry):"
+if [[ -n "$WORK_MD" && ! -f "$WORK_MD" ]]; then
+  echo "  - Re-run triage: $TRIAGE_HELPER <source> <id>"
+  echo "  - Or update .workflow/active_task.json to include a correct taskPath or source+id"
+fi
+if [[ -n "$META" && ! -f "$META" ]]; then
+  echo "  - Resume/backfill metadata: $TRIAGE_HELPER ${TASK_SOURCE:-local} ${TASK_ID:-task} resume"
+elif [[ -n "$META" && -f "$META" ]]; then
+  if [[ -z "$META_STATUS" || -z "$META_PHASE" || -z "$(json_read "$META" '.createdAt')" || -z "$(json_read "$META" '.updatedAt')" ]]; then
+    echo "  - Backfill missing metadata fields: $TRIAGE_HELPER ${TASK_SOURCE:-local} ${TASK_ID:-task} resume"
+  fi
+fi
+if [[ -n "$WORK_MD" && -f "$WORK_MD" ]]; then
+  for section in BRIEF GRILL PLAN LOG META; do
+    count=$(count_section "$section" "$WORK_MD")
+    if [[ "$count" -gt 1 ]]; then
+      echo "  - Manually merge duplicate [$section] sections in $WORK_MD"
+    fi
+  done
+fi
+if [[ -n "$META_STATUS" && "$META_STATUS" =~ ^(done|archived)$ ]]; then
+  echo "  - Choose intentionally: $TRIAGE_HELPER ${TASK_SOURCE:-local} ${TASK_ID:-task} reopen"
+  echo "  - Or leave closed and run cleanup when appropriate."
+fi
+if [[ "$WARNINGS" -eq 0 && "$ERRORS" -eq 0 ]]; then
+  echo "  - No fixes suggested."
+fi
+
+echo
+echo "Validation complete (print-only). warnings=$WARNINGS errors=$ERRORS"
+if [[ "$ERRORS" -gt 0 ]]; then
+  exit 1
+fi

package/sync/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: sync
+description: Synchronizes local RPIV task state (WORK.md) to external trackers (Jira, GitHub, GitLab). Use this to publish progress, update implementation status, and maintain a durable audit trail between local development and remote project management tools.
+---
+
+# Skill: sync
+
+Maintains consistency between local `.workflow` state and the remote source of truth using a single Pi-owned living status comment per task.
+
+## Guardrails
+- **Pre-flight**: Always read `.workflow/active_task.json` and the active `WORK.md` before executing.
+- **Privacy**: NEVER sync secrets, environment variables, or private notes not intended for stakeholders.
+- **Integrity**: Do not modify `[BRIEF]` or `[GRILL]` sections.
+- **Idempotency**: If the remote Pi status already reflects the current local state, do not post or update.
+- **Human safety**: NEVER edit human-authored comments. Only update comments/notes containing the Pi sync marker.
+
+## Living status marker
+Every sync body MUST include this marker at the end:
+
+```md
+<!-- pi-sync-marker -->
+```
+
+Also include the human-readable signature:
+
+```md
+🤖 *Synced by pi (AI assistant) on behalf of the developer.*
+```
+
+The marker identifies the mutable Pi-owned status comment. Human comments after the Pi status must not force new Pi comments.
+
+## Decision Logic (Find / No-op / Update / Create)
+To keep remote history clean, use this hierarchy for Jira, GitHub, and GitLab:
+
+1. Render the new sync body from local `WORK.md`.
+2. Fetch existing comments/notes for the remote issue, PR, or MR.
+3. Search for the newest comment/note containing `<!-- pi-sync-marker -->`.
+4. If a marker comment exists and normalized body is identical: **NO-OP**.
+5. If a marker comment exists and body differs: **UPDATE** that marker comment/note.
+6. If no marker comment exists: **CREATE** one new Pi status comment/note.
+
+Do **not** use latest-comment ownership as the primary decision. Latest-comment-only logic causes infinite comment spam when humans reply after Pi.
+
+## Workflow
+
+### 1. Discovery & State Loading
+- Identify the platform and ID from `.workflow/active_task.json`.
+- Extract **Slices** from `[PLAN]`, **Status** from `[LOG]`, and **Artifacts** such as PR/MR links, commit hashes, and verification output.
+
+### 2. Payload Preparation
+Format the message for two audiences:
+- **Stakeholders**: summarize outcome, current state, and next step.
+- **Developers**: list vertical slices, commit/PR/MR links, and verification evidence.
+- **Signature and marker**: always append both the signature and `<!-- pi-sync-marker -->`.
+
+### 3. Execution
+
+#### Jira
+Use the helper so ADF parsing and marker search stay centralized:
+
+```bash
+cat body.md | <skill_location>/jira_smart_sync.sh <ISSUE_ID>
+```
+
+Behavior:
+- fetch recent comments newest-first, default limit `50`
+- override limit with `PI_SYNC_COMMENT_LIMIT=<n>` if needed
+- find newest marker comment anywhere in the fetched window
+- update marker comment by ID, no-op if identical, create only if no marker exists
+
+#### GitHub Issues / PRs
+Use the issue comments API. PR comments use issue comments for PR body discussion.
+
+Check:
+```bash
+gh api repos/:owner/:repo/issues/<id>/comments --paginate \
+  --jq 'map(select(.body | contains("<!-- pi-sync-marker -->"))) | last'
+```
+
+Update:
+```bash
+gh api -X PATCH repos/:owner/:repo/issues/comments/<comment_id> \
+  -f body=@body.md
+```
+
+Create:
+```bash
+gh issue comment <id> --body-file body.md
+```
+
+Rules:
+- update only a comment containing the marker
+- no-op when normalized body is already current
+- create only when no marker comment exists
+
+#### GitLab Issues / MRs
+Use notes API for issues or merge requests.
+
+Check MR notes:
+```bash
+glab api projects/:id/merge_requests/<iid>/notes --paginate \
+  --jq 'map(select(.body | contains("<!-- pi-sync-marker -->"))) | last'
+```
+
+Update MR note:
+```bash
+glab api -X PUT projects/:id/merge_requests/<iid>/notes/<note_id> \
+  -f body=@body.md
+```
+
+Create MR note:
+```bash
+glab mr note <iid> --message "$(cat body.md)"
+```
+
+Rules:
+- update only a note containing the marker
+- no-op when normalized body is already current
+- create only when no marker note exists
+
+### 4. Local Confirmation
+- Append a timestamped sync record to `WORK.md` `[LOG]` with action: `no-op`, `updated`, or `created`.
+- Do not edit `[BRIEF]` or `[GRILL]`.
+
+## Output Contract
+Return a concise summary:
+- **Target**: platform and issue/PR/MR ID
+- **Action**: no-op / updated existing status / created new status
+- **Reason**: marker found, body identical, marker missing, etc.
+- **Link**: remote comment/note URL if available
+- **Next step**: review, verify, cleanup, or continue implementation

package/sync/design-brief.md

@@ -0,0 +1,39 @@
+# Design Brief: Hardened Tracker Sync (Zero-Trust)
+
+## Skill Type
+Workflow skill with supporting scripts for high-reliability tracker interaction.
+
+## Audience/Context
+Developers using `pi` for RPIV or task-based implementation, reporting progress to Jira, GitHub, or GitLab.
+
+## Trigger Conditions
+- Running `/sync` on a task with source `jira`, `github`, or `gitlab`.
+- Running `/verify` or manually requesting a tracker update.
+
+## Inputs
+- `WORK.md`: factual state for slices, commits, PR/MR links, and test results.
+- Tracker comments/notes API: existing remote status state.
+- `<!-- pi-sync-marker -->`: stable marker used to identify Pi-owned living status comments.
+
+## Outputs
+- Updated existing Pi marker comment/note when content changed.
+- Created new Pi marker comment/note only when no marker exists.
+- No action when the existing Pi marker comment/note already matches local state.
+
+## Key Decisions & Heuristics
+1. **Marker Over Latest Actor**: Search for the newest comment/note containing `<!-- pi-sync-marker -->`; do not rely on the absolute latest comment. Human replies after Pi must not create infinite Pi comments.
+2. **Human Comment Safety**: Only marker-owned Pi comments are mutable. Never edit human-authored comments.
+3. **Recursive ADF Parsing**: Jira Cloud uses Atlassian Document Format. The Jira helper must crawl JSON recursively to find marker/signature text.
+4. **Identity Comparison**: Normalize whitespace before comparing remote and local bodies to avoid unnecessary updates.
+5. **Shell Safety**: Use temporary files and `--body-file`/API body file equivalents where possible to avoid shell length/escaping issues.
+6. **Bounded Search**: Jira helper defaults to the newest 50 comments via `PI_SYNC_COMMENT_LIMIT`; increase only when marker comments are older than the default window.
+
+## File Structure
+- `sync/SKILL.md`: operational instructions for Jira/GitHub/GitLab.
+- `sync/jira_smart_sync.sh`: Jira helper with ADF-aware marker search.
+
+## Success Metrics
+- Zero duplicate Pi comments when progress is static.
+- Zero new Pi comments when a human replies after an existing Pi status comment.
+- Zero overwritten human comments.
+- Reliable detection of Pi's living status comment even after Jira ADF conversion.

package/sync/jira_smart_sync.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+
+# jira_smart_sync.sh - Hardened, Zero-Trust Sync for ACLI
+# Usage: cat body.txt | ./jira_smart_sync.sh <ISSUE_ID>
+#
+# Maintains one Pi-owned living status comment per Jira work item.
+# It finds an existing marker comment anywhere in the fetched window and updates it.
+# It creates a new comment only when no Pi marker comment exists.
+
+set -euo pipefail
+
+ISSUE_ID=${1:-}
+PI_SYNC_MARKER="<!-- pi-sync-marker -->"
+PI_SIGNATURE="🤖 *Synced by pi (AI assistant) on behalf of the developer.*"
+COMMENT_LIMIT=${PI_SYNC_COMMENT_LIMIT:-50}
+TMP_BODY=$(mktemp)
+TMP_JSON=$(mktemp)
+
+cleanup() {
+  rm -f "$TMP_BODY" "$TMP_JSON"
+}
+trap cleanup EXIT
+
+cat > "$TMP_BODY"
+
+if [[ -z "$ISSUE_ID" ]]; then
+  echo "Usage: cat body.txt | $0 <ISSUE_ID>"
+  exit 1
+fi
+
+# Fetch newest comments first. The marker search is not latest-comment-only;
+# the limit only bounds API cost/noise. Increase PI_SYNC_COMMENT_LIMIT if needed.
+acli jira workitem comment list --key "$ISSUE_ID" --json --limit "$COMMENT_LIMIT" --order "-created" > "$TMP_JSON"
+
+export PI_SYNC_MARKER
+export PI_SIGNATURE
+export NEW_BODY_FILE="$TMP_BODY"
+export COMMENTS_JSON_FILE="$TMP_JSON"
+
+MATCH_DATA=$(python3 <<'PY'
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+marker = os.environ.get("PI_SYNC_MARKER", "<!-- pi-sync-marker -->")
+signature = os.environ.get("PI_SIGNATURE", "")
+new_body_file = Path(os.environ["NEW_BODY_FILE"])
+comments_json_file = Path(os.environ["COMMENTS_JSON_FILE"])
+
+
+def get_text(obj):
+    if obj is None:
+        return ""
+    if isinstance(obj, str):
+        return obj
+    if isinstance(obj, list):
+        return "\n".join(get_text(x) for x in obj)
+    if isinstance(obj, dict):
+        # Common flattened outputs first.
+        rendered = obj.get("renderedBody")
+        if isinstance(rendered, str):
+            return rendered
+        body = obj.get("body")
+        if isinstance(body, str):
+            return body
+        # Atlassian Document Format text nodes.
+        if obj.get("type") == "text":
+            return obj.get("text", "")
+        content = obj.get("content")
+        if content:
+            return get_text(content)
+        return "\n".join(get_text(v) for v in obj.values() if isinstance(v, (dict, list, str)))
+    return str(obj)
+
+
+def normalize(text):
+    # Jira/ACLI rendering can alter blank lines and trailing whitespace. Keep the
+    # comparison conservative: avoid duplicates when content is materially equal.
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    lines = [line.rstrip() for line in text.strip().split("\n")]
+    return re.sub(r"\n{3,}", "\n\n", "\n".join(lines)).strip()
+
+
+def comment_id(comment):
+    for key in ("id", "commentId", "comment_id"):
+        value = comment.get(key) if isinstance(comment, dict) else None
+        if value is not None:
+            return str(value)
+    return ""
+
+
+def unwrap_comments(data):
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        for key in ("comments", "values", "results", "data"):
+            value = data.get(key)
+            if isinstance(value, list):
+                return value
+        if "id" in data:
+            return [data]
+    return []
+
+try:
+    new_text = new_body_file.read_text().strip()
+    data = json.loads(comments_json_file.read_text())
+    comments = unwrap_comments(data)
+
+    if not comments:
+        print("CREATE|no existing comments")
+        raise SystemExit(0)
+
+    # Comments are fetched newest first. Pick the newest Pi-owned marker comment,
+    # not necessarily the absolute latest comment. Human comments remain untouched.
+    for comment in comments:
+        text = get_text(comment.get("body", comment)) if isinstance(comment, dict) else get_text(comment)
+        owns_comment = marker in text or (signature and signature in text)
+        if not owns_comment:
+            continue
+
+        cid = comment_id(comment)
+        if not cid:
+            print("CREATE|marker found without id")
+            raise SystemExit(0)
+
+        if normalize(new_text) == normalize(text):
+            print(f"NOOP|{cid}")
+        else:
+            print(f"UPDATE|{cid}")
+        raise SystemExit(0)
+
+    print("CREATE|no pi marker comment")
+except Exception as exc:
+    # Fail-open to create: better to keep stakeholder visibility than silently drop sync.
+    print(f"CREATE|parse fallback: {exc}")
+PY
+)
+
+ACTION_CODE=$(echo "$MATCH_DATA" | cut -d'|' -f1)
+TARGET_ID=$(echo "$MATCH_DATA" | cut -d'|' -f2-)
+
+case "$ACTION_CODE" in
+    NOOP)
+        echo "SYNC: Existing Pi status is already current (ID: $TARGET_ID)."
+        ;;
+    UPDATE)
+        echo "SYNC: Updating existing Pi status (ID: $TARGET_ID)."
+        acli jira workitem comment update --key "$ISSUE_ID" --id "$TARGET_ID" --body-file "$TMP_BODY"
+        ;;
+    *)
+        echo "SYNC: Creating Pi status comment ($TARGET_ID)."
+        acli jira workitem comment create --key "$ISSUE_ID" --body-file "$TMP_BODY"
+        ;;
+esac