@snappedly-tools/shipyard 0.5.0 → 0.6.0

package/dist/templates/parallel-planner/block-scope.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root=${1:?scope root required}
+failed=${2:?failed issue required}
+repo=${3:?GitHub repository required}
+scope=${4:?scope issue numbers required}
+branch=${5:-shipyard/issue-$root}
+[[ "$root" =~ ^[0-9]+$ && "$failed" =~ ^[0-9]+$ ]] || { echo "Invalid issue number" >&2; exit 1; }
+[[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GitHub repository" >&2; exit 1; }
+[[ "$scope" =~ ^[0-9]+(,[0-9]+)*$ && ( "$scope" == "$root" || "$scope" == "$root,"* ) && ",$scope," == *",$failed,"* ]] || {
+  echo "Invalid blocked issue scope" >&2; exit 1;
+}
+[[ "$branch" == "shipyard/issue-$root" || "$branch" == "shipyard/spec-$root" ]] || { echo "Invalid scope branch" >&2; exit 1; }
+reason=$(cat)
+[[ -n "$reason" ]] || { echo "Missing failure reason" >&2; exit 1; }
+reason_hash=$(printf '%s' "$reason" | git hash-object --stdin)
+pending_dir=$(git rev-parse --git-path shipyard-pending)
+mkdir -p "$pending_dir"
+umask 077
+pending_file="$pending_dir/$root-$failed.pending"
+trap 'rm -f "${pending_tmp:-}"' EXIT
+confirmed=""
+if [[ -f "$pending_file" ]]; then
+  IFS=$'\t' read -r old_root old_failed old_repo old_scope old_branch old_confirmed < "$pending_file"
+  if [[ "$old_root" == "$root" && "$old_failed" == "$failed" && "$old_repo" == "$repo" && "$old_scope" == "$scope" && "$old_branch" == "$branch" ]]; then
+    confirmed=${old_confirmed:-}
+  fi
+fi
+write_pending() {
+  pending_tmp=$(mktemp "$pending_file.XXXXXX")
+  printf '%s\t%s\t%s\t%s\t%s\t%s\n%s' "$root" "$failed" "$repo" "$scope" "$branch" "$confirmed" "$reason" > "$pending_tmp"
+  mv "$pending_tmp" "$pending_file"
+}
+confirm_blocked() {
+  if [[ ",$confirmed," != *",$1,"* ]]; then
+    confirmed=${confirmed:+$confirmed,}$1
+    write_pending
+  fi
+}
+write_pending
+
+remove_issue_status() {
+  local labels
+  if gh issue edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh issue view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from issue #$1" >&2
+    return 75
+  fi
+}
+remove_pr_status() {
+  local labels
+  if gh pr edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh pr view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from PR #$1" >&2
+    return 75
+  fi
+}
+comment_once() {
+  local comments
+  if comments=$(gh issue view "$1" --repo "$repo" --json comments --jq '.comments[].body'); then
+    if grep -Fq "$3" <<< "$comments"; then return 0; fi
+  fi
+  gh issue comment "$1" --repo "$repo" --body "$2"
+}
+
+gh label create shipyard:blocked --repo "$repo" --color B60205 --description 'Shipyard work needs intervention' --force
+status_synced=true
+IFS=',' read -ra affected_ids <<< "$scope"
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    gh issue edit "$affected_id" --repo "$repo" --add-label shipyard:blocked
+    confirm_blocked "$affected_id"
+  done
+  if ! gh issue edit "$root" --repo "$repo" --add-label shipyard:blocked; then
+    echo "Warning: could not update spec #$root status" >&2
+    status_synced=false
+  fi
+else
+  gh issue edit "$root" --repo "$repo" --add-label shipyard:blocked
+  confirm_blocked "$root"
+fi
+
+status=0
+marker="shipyard:blocked:$root:$failed:$reason_hash"
+comment_once "$failed" "Shipyard could not complete this issue. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to the affected ticket.
+
+<!-- $marker:failed -->" "$marker:failed" || status=75
+if [[ "$root" != "$failed" ]]; then
+  comment_once "$root" "Shipyard paused this spec because linked ticket #$failed failed. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to each unfinished ticket.
+
+<!-- $marker:parent -->" "$marker:parent" || status=75
+fi
+if [[ "$branch" == "shipyard/spec-$root" && "$failed" == "$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    comment_once "$affected_id" "Shipyard could not complete this ticket during the spec attempt. Reason: $reason
+
+Work was not handed off. To retry, resolve the problem, remove shipyard:blocked, and add shipyard to the affected ticket.
+
+<!-- $marker:ticket:$affected_id -->" "$marker:ticket:$affected_id" || status=75
+  done
+fi
+
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  if ! remove_issue_status "$root" shipyard:outstanding-tasks; then
+    echo "Warning: could not clear spec status" >&2
+    status_synced=false
+  fi
+  if ! remove_issue_status "$root" shipyard:complete; then
+    echo "Warning: could not clear spec status" >&2
+    status_synced=false
+  fi
+else
+  remove_issue_status "$root" shipyard:outstanding-tasks || status=75
+  remove_issue_status "$root" shipyard:complete || status=75
+fi
+if [[ "$branch" == "shipyard/spec-$root" ]]; then
+  for affected_id in "${affected_ids[@]:1}"; do
+    remove_issue_status "$affected_id" shipyard:pending || status=75
+  done
+else
+  remove_issue_status "$root" shipyard:pending || status=75
+fi
+
+if ! pr_number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty'); then
+  echo "Warning: could not inspect PR status" >&2
+  status_synced=false
+  pr_number=""
+fi
+if [[ -n "$pr_number" ]]; then
+  if ! gh pr edit "$pr_number" --repo "$repo" --add-label shipyard:blocked; then
+    echo "Warning: could not update PR status" >&2
+    status_synced=false
+  fi
+  if ! remove_pr_status "$pr_number" shipyard:outstanding-tasks; then
+    echo "Warning: could not clear PR status" >&2
+    status_synced=false
+  fi
+  if ! remove_pr_status "$pr_number" shipyard:complete; then
+    echo "Warning: could not clear PR status" >&2
+    status_synced=false
+  fi
+fi
+if [[ "$status" -eq 0 && "$status_synced" == true ]]; then
+  IFS=',' read -ra scope_ids <<< "$scope"
+  for scope_id in "${scope_ids[@]}"; do
+    labels=$(gh issue view "$scope_id" --repo "$repo" --json labels --jq '.labels[].name')
+    if grep -Fxq shipyard <<< "$labels"; then
+      gh issue edit "$scope_id" --repo "$repo" --remove-label shipyard
+    fi
+  done
+  rm -f "$pending_file"
+fi
+exit "$status"

package/dist/templates/parallel-planner/conflict-prompt.md

@@ -0,0 +1,22 @@
+# Resolve a spec ticket integration conflict
+
+Ticket #{{TASK_ID}} has a cherry-pick conflict while integrating commits `{{COMMITS}}` into spec branch `{{BRANCH}}`.
+
+Follow `/implement-spec` as the assigned integrator. Read the parent and every scoped ticket, inspect `git status` and the conflicted files, and resolve the conflict while preserving both the ticket's requirements and changes already integrated into the spec branch. Continue the cherry-pick; do not abort or skip the ticket. If the cherry-pick includes multiple commits, continue until the sequence finishes. Run affected checks, commit the resolution, and leave the worktree clean. The selected workflow will then run its normal whole-spec integration and review stages.
+
+The Git failure was:
+
+```text
+{{CONFLICT}}
+```
+
+If the conflict cannot be resolved or checked, explain why and stop without a completion marker. After resolution, report `Checks: <commands and results>` and the integrated ticket:
+
+<handoff>...</handoff>
+<promise>COMPLETE</promise>
+
+## Resolved spec scope
+
+```json
+{{SCOPE}}
+```

package/dist/templates/parallel-planner/handoff.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+issue=${1:?issue number required}
+branch=${2:?branch required}
+base=${3:?target branch required}
+repo=${4:?GitHub repository required}
+scope=${5:-$issue}
+outstanding=${6:--}
+previously_completed=${7:--}
+[[ "$issue" =~ ^[0-9]+$ && ( "$branch" == "shipyard/issue-$issue" || "$branch" == "shipyard/spec-$issue" ) ]] || {
+  echo "Invalid issue or branch for PR handoff" >&2; exit 1;
+}
+[[ "$base" =~ ^[A-Za-z0-9._/-]+$ ]] || {
+  echo "Invalid target branch for PR handoff" >&2; exit 1;
+}
+
+[[ "$scope" =~ ^[0-9]+(,[0-9]+)*$ && ( "$scope" == "$issue" || "$scope" == "$issue,"* ) ]] || { echo "Invalid PR scope" >&2; exit 1; }
+[[ "$outstanding" == - || "$outstanding" =~ ^[0-9]+(,[0-9]+)*$ ]] || { echo "Invalid outstanding tickets" >&2; exit 1; }
+[[ "$previously_completed" == - || "$previously_completed" =~ ^[0-9]+(,[0-9]+)*$ ]] || { echo "Invalid completed tickets" >&2; exit 1; }
+evidence=$(cat)
+[[ -n "$evidence" ]] || { echo "Missing verification evidence" >&2; exit 1; }
+grep -Eiq '(^|[[:space:]])Checks:' <<< "$evidence" || { echo "Missing check evidence" >&2; exit 1; }
+grep -Eiq '(^|[[:space:]])Review:' <<< "$evidence" || { echo "Missing review evidence" >&2; exit 1; }
+[[ -z $(git status --porcelain) ]] || {
+  echo "Uncommitted changes prevent PR handoff" >&2; exit 1;
+}
+base_ref=$(git rev-parse --verify "refs/remotes/origin/$base^{commit}") || {
+  echo "Target branch is unavailable in the sandbox" >&2; exit 1;
+}
+branch_base=$base_ref
+if ! git merge-base --is-ancestor "$base_ref" HEAD; then
+  branch_base=$(git merge-base "$base_ref" HEAD) || {
+    echo "PR branch has no common base with the target branch" >&2; exit 1;
+  }
+fi
+[[ -n $(git log "$branch_base"..HEAD --format=%H) ]] || {
+  echo "No verified commit to publish" >&2; exit 1;
+}
+
+[[ "$repo" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] || { echo "Invalid GitHub repository" >&2; exit 1; }
+remove_issue_label() {
+  local labels
+  if gh issue edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh issue view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from issue #$1; retry handoff when GitHub is available" >&2
+    return 75
+  fi
+}
+remove_pr_label() {
+  local labels
+  if gh pr edit "$1" --repo "$repo" --remove-label "$2"; then return 0; fi
+  labels=$(gh pr view "$1" --repo "$repo" --json labels --jq '.labels[].name') || return 75
+  if grep -Fxq "$2" <<< "$labels"; then
+    echo "Could not remove $2 from PR #$1; retry handoff when GitHub is available" >&2
+    return 75
+  fi
+}
+title=$(gh issue view "$issue" --repo "$repo" --json title --jq .title)
+body=$(mktemp)
+trap 'rm -f "$body"' EXIT
+links=""
+implemented=""
+IFS=',' read -ra scope_ids <<< "$scope"
+for scope_id in "${scope_ids[@]}"; do links+="#$scope_id "; done
+for ((i=1; i<${#scope_ids[@]}; i++)); do implemented+="#${scope_ids[i]} "; done
+if [[ "$previously_completed" != - ]]; then
+  IFS=',' read -ra completed_ids <<< "$previously_completed"
+  for completed_id in "${completed_ids[@]}"; do links+="#$completed_id "; implemented+="#$completed_id "; done
+fi
+if [[ "$outstanding" != - ]]; then
+  IFS=',' read -ra outstanding_ids <<< "$outstanding"
+  for outstanding_id in "${outstanding_ids[@]}"; do links+="#$outstanding_id "; done
+fi
+printf 'Source issues: %s\nImplemented tickets: %s\n\n## Verification and review\n\n%s\n\nHuman review and merge required.\n\n<!-- shipyard:verified-handoff -->\n' "$links" "$implemented" "$evidence" > "$body"
+
+# Keep Git credentials inside the disposable sandbox, not in the host worktree.
+git remote set-url origin "https://github.com/$repo.git"
+git -c credential.helper='!gh auth git-credential' push -u origin "HEAD:refs/heads/$branch"
+number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty')
+if [[ -z "$number" ]]; then
+  gh pr create --repo "$repo" --head "$branch" --base "$base" --title "$title" --body-file "$body" --draft
+  number=$(gh pr list --repo "$repo" --head "$branch" --state open --json number --jq '.[0].number // empty')
+fi
+[[ -n "$number" ]] || { echo "PR publication did not return an open PR" >&2; exit 1; }
+gh pr edit "$number" --repo "$repo" --body-file "$body"
+draft=$(gh pr view "$number" --repo "$repo" --json isDraft --jq .isDraft)
+url=$(gh pr view "$number" --repo "$repo" --json url --jq .url)
+[[ -n "$url" ]] || { echo "PR publication did not return a URL" >&2; exit 1; }
+if [[ "$draft" == true ]]; then gh pr ready "$number" --repo "$repo" || true; fi
+if ! current_draft=$(gh pr view "$number" --repo "$repo" --json isDraft --jq .isDraft) ||
+   ! current_state=$(gh pr view "$number" --repo "$repo" --json state --jq .state); then
+  echo "Could not confirm PR readiness; retry publication when GitHub is available" >&2
+  exit 75
+fi
+if [[ "$current_draft" != false || "$current_state" != OPEN ]]; then
+  echo "PR did not become ready for human review" >&2
+  exit 1
+fi
+for ((i=1; i<${#scope_ids[@]}; i++)); do
+  if ! gh issue edit "${scope_ids[i]}" --repo "$repo" --add-label shipyard:complete; then
+    echo "Could not mark ticket #${scope_ids[i]} complete; retry issue completion when GitHub is available" >&2
+    exit 75
+  fi
+  remove_issue_label "${scope_ids[i]}" shipyard:blocked
+  remove_issue_label "${scope_ids[i]}" shipyard:pending
+done
+status_label=shipyard:complete
+status_color=0E8A16
+status_description='Shipyard work ready for human review'
+if [[ "$outstanding" != - ]]; then
+  status_label=shipyard:outstanding-tasks
+  status_color=FBCA04
+  status_description='Spec has uncompleted tickets'
+  for outstanding_id in "${outstanding_ids[@]}"; do
+    labels=$(gh issue view "$outstanding_id" --repo "$repo" --json labels --jq '.labels[].name') || exit 75
+    if grep -Fxq shipyard:blocked <<< "$labels" && ! grep -Fxq shipyard:complete <<< "$labels"; then
+      status_label=shipyard:blocked
+      status_color=B60205
+      status_description='Shipyard work needs intervention'
+      break
+    fi
+  done
+fi
+status_synced=true
+if ! gh label create "$status_label" --repo "$repo" --color "$status_color" --description "$status_description" --force; then
+  echo "Warning: could not create $status_label" >&2
+  status_synced=false
+fi
+if ! gh issue edit "$issue" --repo "$repo" --add-label "$status_label"; then
+  if [[ "$branch" == "shipyard/issue-$issue" ]]; then
+    echo "Could not mark ticket #$issue complete; retry issue completion when GitHub is available" >&2
+    exit 75
+  fi
+  echo "Warning: could not update spec #$issue status" >&2
+  status_synced=false
+fi
+for stale_label in shipyard:complete shipyard:outstanding-tasks shipyard:blocked; do
+  if [[ "$stale_label" != "$status_label" ]]; then
+    if ! remove_issue_label "$issue" "$stale_label"; then
+      if [[ "$branch" == "shipyard/issue-$issue" ]]; then exit 75; fi
+      echo "Warning: could not clear $stale_label from spec #$issue" >&2
+      status_synced=false
+    fi
+  fi
+done
+if [[ "$branch" == "shipyard/issue-$issue" ]]; then remove_issue_label "$issue" shipyard:pending; fi
+if ! gh pr edit "$number" --repo "$repo" --add-label "$status_label"; then
+  echo "Warning: could not update PR #$number status" >&2
+  status_synced=false
+fi
+for stale_label in shipyard:complete shipyard:outstanding-tasks shipyard:blocked; do
+  if [[ "$stale_label" != "$status_label" ]]; then
+    if ! remove_pr_label "$number" "$stale_label"; then
+      echo "Warning: could not clear $stale_label from PR #$number" >&2
+      status_synced=false
+    fi
+  fi
+done
+if [[ "$status_synced" == true ]]; then
+  for scope_id in "${scope_ids[@]}"; do
+    if ! labels=$(gh issue view "$scope_id" --repo "$repo" --json labels --jq '.labels[].name'); then
+      echo "Warning: could not inspect activation on issue #$scope_id; the next invocation will retry cleanup" >&2
+      continue
+    fi
+    if grep -Fxq shipyard <<< "$labels"; then
+      gh issue edit "$scope_id" --repo "$repo" --remove-label shipyard ||
+        echo "Warning: could not remove activation from issue #$scope_id; the next invocation will retry cleanup" >&2
+    fi
+  done
+else
+  echo "Warning: status labels need reconciliation; retaining ticket activation" >&2
+fi
+printf '%s\n' "$url"

package/dist/templates/parallel-planner/implement-prompt.md

@@ -1,62 +1,16 @@
-# TASK
+# Assigned executable ticket #{{TASK_ID}}: {{ISSUE_TITLE}}
 
-Fix issue {{TASK_ID}}: {{ISSUE_TITLE}}
+Work only on branch `{{BRANCH}}`. Read `gh issue view {{TASK_ID}} --comments`, `AGENTS.md`, `CONTEXT.md`, `docs/agents/workflow.md`, and relevant ADRs.
 
-Pull in the issue using `{{VIEW_TASK_COMMAND}}`. If it has a parent PRD, pull that in too.
+Follow `/implement` as a ticket worker assigned by the existing parallel planner. Use `/tdd` for changed logic and local `/code-cleanup`; run focused tests, typechecking, and scoped formatting. Reinstall dependencies for the candidate with `bash .shipyard/setup.sh` after manifest changes. Commit and self-check. Return to the planner workflow: do not launch `/implement-spec`, another orchestration or review chain, merge, create a PR, or close this issue. The selected template's later stages own those steps.
 
-Only work on the issue specified.
+If incomplete, explain the blocker without a completion marker. Once the ticket has a verified commit, give scope, `Checks: <commands and results>`, and limitations:
 
-Work on branch {{BRANCH}}. Make commits and run tests.
+<handoff>...</handoff>
+<promise>COMPLETE</promise>
 
-# CONTEXT
+For a child assignment, parent/spec scope is below. Read the parent and sibling tickets for context, but implement only assigned ticket #{{TASK_ID}}. The whole-spec integration stage owns `/implement-spec`.
 
-Here are the last 10 commits:
-
-<recent-commits>
-
-!`git log -n 10 --format="%H%n%ad%n%B---" --date=short`
-
-</recent-commits>
-
-# EXPLORATION
-
-Explore the repo and fill your context window with relevant information that will allow you to complete the task.
-
-Pay extra attention to test files that touch the relevant parts of the code.
-
-# EXECUTION
-
-If applicable, use RGR to complete the task.
-
-1. RED: write one test
-2. GREEN: write the implementation to pass that test
-3. REPEAT until done
-4. REFACTOR the code
-
-# FEEDBACK LOOPS
-
-Before committing, read the repository's configured feedback-loop contract and run every applicable check for this change. Use the configured static check and focused behavior tests when they exist; include formatting, build, or broader checks when the contract or change requires them. Fix failures before committing.
-
-# COMMIT
-
-Make a git commit. The commit message must:
-
-1. Start with `RALPH:` prefix
-2. Include task completed + PRD reference
-3. Key decisions made
-4. Files changed
-5. Blockers or notes for next iteration
-
-Keep it concise.
-
-# THE ISSUE
-
-If the task is not complete, leave a comment on the issue with what was done.
-
-Do not close the issue - this will be done later.
-
-Once complete, output <promise>COMPLETE</promise>.
-
-# FINAL RULES
-
-ONLY WORK ON A SINGLE TASK.
+```json
+{{SCOPE}}
+```