@svayam-opensource/prj 0.5.1

package/scripts/add-repo.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Script: add-repo
+# Purpose: Adds a new repository to an active project when scope expands.
+# Usage:   bash add-repo.sh <project_id> <repo_url> <role> <added_reason> [base_branch]
+# Compliance: C02 (POL-062 to POL-066)
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+# ── Inputs ────────────────────────────────────────────────────────────────────
+
+PROJECT_ID="${1:-}"
+REPO_URL="${2:-}"
+ROLE="${3:-}"
+ADDED_REASON="${4:-}"
+BASE_BRANCH="${5:-}"
+
+[[ -n "$PROJECT_ID"    ]] || hard_stop "Usage: $0 <project_id> <repo_url> <role> <added_reason> [base_branch]"
+[[ -n "$REPO_URL"      ]] || hard_stop "Usage: $0 <project_id> <repo_url> <role> <added_reason> [base_branch]"
+[[ -n "$ROLE"          ]] || hard_stop "Usage: $0 <project_id> <repo_url> <role> <added_reason> [base_branch]"
+[[ -n "$ADDED_REASON"  ]] || hard_stop "Usage: $0 <project_id> <repo_url> <role> <added_reason> [base_branch]"
+
+# Validate role value
+case "$ROLE" in
+  primary|dependency|read-only) ;;
+  *) hard_stop "Invalid role '$ROLE'. Must be: primary | dependency | read-only" ;;
+esac
+
+echo "=== add-repo: $PROJECT_ID"
+echo "    Repo:   $REPO_URL"
+echo "    Role:   $ROLE"
+echo "    Reason: $ADDED_REASON"
+echo ""
+
+PROJECT_YAML=$(get_project_yaml "$PROJECT_ID")
+check_project_exists "$PROJECT_ID"
+
+# ── Pre-conditions ────────────────────────────────────────────────────────────
+
+require_project_status "$PROJECT_YAML" "active"
+
+CURRENT_USER=$(git config user.email 2>/dev/null || echo "")
+ASSIGNED_TO=$(yaml_get "$PROJECT_YAML" "assigned_to")        # display/audit cache
+GH_PROJECT=$(yaml_get "$PROJECT_YAML" "github_project")
+is_authorized_for_project "$GH_PROJECT" "$ASSIGNED_TO" \
+  || hard_stop "Not authorized: '$CURRENT_USER' needs write access to the project's GitHub Project ($GH_PROJECT)."
+
+# Check repo is not already in the project
+python3 - "$PROJECT_YAML" "$REPO_URL" <<'PY'
+import sys, yaml
+c = yaml.safe_load(open(sys.argv[1]))
+for r in (c.get('repos') or []):
+    if r and r.get('url') == sys.argv[2]:
+        print(f"Repo already in project: {sys.argv[2]}")
+        sys.exit(1)
+PY
+
+BRANCH=$(project_branch_for_id "$PROJECT_ID")
+TODAY=$(today)
+
+# Prompt for base_branch if not provided
+if [[ -z "$BASE_BRANCH" ]]; then
+  printf "  Base branch for '%s' [%s]: " "$REPO_URL" "$DEFAULT_CODE_BRANCH"
+  read -r input_base
+  BASE_BRANCH="${input_base:-$DEFAULT_CODE_BRANCH}"
+fi
+
+REPO_NAME=$(get_repo_name "$REPO_URL")
+REPO_DIR="$AGENT_WORK_ROOT/$PROJECT_ID/$REPO_NAME"
+
+# ── Clone and create branch ───────────────────────────────────────────────────
+
+mkdir -p "$AGENT_WORK_ROOT/$PROJECT_ID"
+
+if [[ -e "$REPO_DIR/.git" ]]; then
+  info "Already cloned — fetching..."
+  git -C "$REPO_DIR" fetch origin
+else
+  info "Cloning $REPO_URL → $REPO_DIR..."
+  git clone "$REPO_URL" "$REPO_DIR" \
+    || hard_stop "Clone failed for $REPO_URL"
+fi
+
+git -C "$REPO_DIR" checkout "$BASE_BRANCH" \
+  || hard_stop "Base branch '$BASE_BRANCH' not found in $REPO_URL"
+git -C "$REPO_DIR" pull origin "$BASE_BRANCH" 2>/dev/null || true
+
+if git -C "$REPO_DIR" rev-parse --verify "$BRANCH" &>/dev/null; then
+  hard_stop "Branch '$BRANCH' already exists in $REPO_URL — investigate before proceeding."
+fi
+
+git -C "$REPO_DIR" checkout -b "$BRANCH"
+git -C "$REPO_DIR" push -u origin "$BRANCH" \
+  || hard_stop "Failed to push '$BRANCH' to $REPO_URL"
+info "Branch '$BRANCH' pushed to $REPO_URL"
+
+# ── Update project.yaml repos[] ──────────────────────────────────────────────
+
+python3 - "$PROJECT_YAML" "$REPO_URL" "$ROLE" "$BASE_BRANCH" "$TODAY" "$ADDED_REASON" <<'PY'
+import sys, yaml
+pf, url, role, base, today, reason = sys.argv[1:]
+with open(pf) as f:
+    c = yaml.safe_load(f)
+if not c.get('repos'):
+    c['repos'] = []
+c['repos'].append({
+    'url': url, 'role': role, 'base_branch': base,
+    'added_at': today, 'added_reason': reason,
+})
+with open(pf, 'w') as f:
+    yaml.dump(c, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+PY
+
+cd "$REPO_ROOT"
+git checkout "$BRANCH"
+git add "projects/$PROJECT_ID/project.yaml"
+git commit -m "add-repo: $REPO_NAME to $PROJECT_ID"
+git push origin "$BRANCH"
+
+echo ""
+echo "=== Repo added successfully!"
+echo "    Repo:        $REPO_URL"
+echo "    Role:        $ROLE"
+echo "    Base branch: $BASE_BRANCH"
+echo "    Local clone: $REPO_DIR"

package/scripts/cancel.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# Script: cancel
+# Purpose: Cancels a project. Archives all branches. No knowledge close.
+# Usage:   bash cancel.sh <project_id> <cancellation_reason>
+# Compliance: C01 for cancellation_reason requirement (POL-052, POL-070)
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+# ── Inputs ────────────────────────────────────────────────────────────────────
+
+PROJECT_ID="${1:-}"
+CANCELLATION_REASON="${2:-}"
+
+[[ -n "$PROJECT_ID"           ]] || hard_stop "Usage: $0 <project_id> <cancellation_reason>"
+[[ -n "$CANCELLATION_REASON"  ]] || hard_stop "cancellation_reason is required (C01)."
+
+echo "=== cancel: $PROJECT_ID"
+echo "    Reason: $CANCELLATION_REASON"
+echo ""
+
+PROJECT_YAML=$(get_project_yaml "$PROJECT_ID")
+check_project_exists "$PROJECT_ID"
+
+# ── Pre-conditions ────────────────────────────────────────────────────────────
+
+require_any_project_status "$PROJECT_YAML" "active" "paused"
+
+# The person cancelling must be authorized on the project — assigned_to
+# individual or a member of the assigned_to team (GitHub-Project write, POL-046).
+# (#62/C11: the old 'locked_by' gate was dead — locked_by is never written by
+# any script, so the guard short-circuited on empty → any user could cancel any
+# project. Mirror the standard authz used by create-task.sh / seed.sh.)
+CURRENT_USER=$(git config user.email 2>/dev/null || echo "")
+ASSIGNED_TO=$(yaml_get "$PROJECT_YAML" "assigned_to")        # display/audit cache
+GH_PROJECT=$(yaml_get "$PROJECT_YAML" "github_project")
+is_authorized_for_project "$GH_PROJECT" "$ASSIGNED_TO" \
+  || hard_stop "You ($CURRENT_USER) are not authorized on this project — you need write access to its GitHub Project ($GH_PROJECT)."
+
+BRANCH=$(project_branch_for_id "$PROJECT_ID")
+
+confirm "Cancelling '$PROJECT_ID' is irreversible (branches archived, not merged). Continue?"
+
+# ── Archive all branches (continue-on-error, idempotent) ──────────────────────
+# #64/H5: archiving is per-repo and must NOT leave inconsistent state. Each repo
+# is handled independently: if the 'archive/<branch>' tag already exists the repo
+# is treated as already-archived and skipped, so a re-run after a partial failure
+# completes cleanly instead of hard-stopping on "tag exists". Failures are
+# collected (never abort the loop) so every repo is attempted; the status flip
+# below is gated on whether everything that was attempted actually succeeded.
+
+ARCHIVE_FAILURES=()        # human-readable label of each repo that did not archive
+
+# Idempotent wrapper around archive_branch: skips when the archive tag already
+# exists (local or remote), and converts a hard_stop into a recorded failure so
+# the loop can continue. $1=repo label (for summary), $2=git dir, $3=branch.
+archive_branch_safe() {
+  local label="$1" dir="$2" branch="$3" tag="archive/$branch"
+  if git -C "$dir" rev-parse --verify "refs/tags/$tag" &>/dev/null \
+     || git -C "$dir" ls-remote --exit-code --tags origin "$tag" &>/dev/null; then
+    info "Archive tag '$tag' already exists in $label — skipping (idempotent)."
+    git -C "$dir" branch -D "$branch" 2>/dev/null || true
+    return 0
+  fi
+  # archive_branch hard_stops (exit) on failure; run it in a subshell so a
+  # failure becomes a non-zero status we can record rather than aborting cancel.
+  if ( archive_branch "$dir" "$branch" ); then
+    return 0
+  fi
+  warn "Failed to archive branch '$branch' in $label — recorded; continuing."
+  ARCHIVE_FAILURES+=("$label")
+  return 1
+}
+
+# ── Archive workspace branch ──────────────────────────────────────────────────
+
+echo "Archiving workspace branch..."
+cd "$REPO_ROOT"
+git fetch origin "$BRANCH" 2>/dev/null || true
+if git rev-parse --verify "$BRANCH" &>/dev/null 2>&1 || git ls-remote --exit-code origin "$BRANCH" &>/dev/null; then
+  archive_branch_safe "workspace repo" "$REPO_ROOT" "$BRANCH" || true
+else
+  warn "Branch '$BRANCH' not found in workspace repo — skipping archive."
+fi
+
+# ── Archive each code repo branch ────────────────────────────────────────────
+
+while IFS= read -r repo_url; do
+  REPO_NAME=$(get_repo_name "$repo_url")
+  REPO_DIR="$(repo_clone_dir "$PROJECT_ID" "$REPO_NAME")"
+  if [[ ! -e "$REPO_DIR/.git" ]]; then
+    warn "Repo $REPO_NAME not cloned locally — archiving via remote only."
+    TMP_DIR=$(mktemp -d)
+    if git clone --branch "$BRANCH" --single-branch "$repo_url" "$TMP_DIR" 2>/dev/null; then
+      archive_branch_safe "$REPO_NAME" "$TMP_DIR" "$BRANCH" || true
+    elif git ls-remote --exit-code --tags "$repo_url" "archive/$BRANCH" &>/dev/null; then
+      info "Archive tag 'archive/$BRANCH' already exists in $REPO_NAME — skipping (idempotent)."
+    else
+      warn "Could not archive branch '$BRANCH' in $repo_url — recorded; continuing."
+      ARCHIVE_FAILURES+=("$REPO_NAME")
+    fi
+    rm -rf "$TMP_DIR"
+    continue
+  fi
+  git -C "$REPO_DIR" fetch origin "$BRANCH" 2>/dev/null || true
+  if git -C "$REPO_DIR" rev-parse --verify "$BRANCH" &>/dev/null 2>&1 \
+     || git -C "$REPO_DIR" rev-parse --verify "refs/tags/archive/$BRANCH" &>/dev/null \
+     || git -C "$REPO_DIR" ls-remote --exit-code --tags origin "archive/$BRANCH" &>/dev/null; then
+    archive_branch_safe "$REPO_NAME" "$REPO_DIR" "$BRANCH" || true
+  else
+    warn "Branch '$BRANCH' not found in $REPO_NAME — skipping archive."
+  fi
+done < <(get_project_repos "$PROJECT_YAML")
+
+# ── Gate the status flip on a clean archive ───────────────────────────────────
+# H5: only flip status to 'cancelled' if every repo we attempted archived
+# successfully. If any failed, stop BEFORE mutating status so the project stays
+# active/paused and the operator can re-run — the re-run is idempotent (already-
+# archived repos are skipped) and will complete the remaining repos.
+if [[ ${#ARCHIVE_FAILURES[@]} -gt 0 ]]; then
+  hard_stop "Archive incomplete for: ${ARCHIVE_FAILURES[*]}. Status NOT changed — re-run cancel after resolving (already-archived repos will be skipped)."
+fi
+
+# ── Record cancellation ──────────────────────────────────────────────────────
+# project.yaml status is recorded on the project branch (preserved in the
+# archive tag). The registry index entry is flipped to 'cancelled' on
+# $DEFAULT_BRANCH, where it lives (authored at seed).
+
+TODAY=$(today)
+cd "$REPO_ROOT"
+if [[ -f "$PROJECT_YAML" ]]; then
+  yaml_set "$PROJECT_YAML" "status"               "cancelled"
+  yaml_set "$PROJECT_YAML" "cancelled_at"         "$TODAY"
+  yaml_set "$PROJECT_YAML" "cancellation_reason"  "$CANCELLATION_REASON"
+  git add "projects/$PROJECT_ID/project.yaml"
+  if ! git diff --cached --quiet; then
+    git commit -m "cancel: $PROJECT_ID — $CANCELLATION_REASON"
+    git push origin "$BRANCH" 2>/dev/null || true
+  fi
+fi
+
+registry_set_status_on_main "$PROJECT_ID" "cancelled"
+project_readme_mirror "$PROJECT_ID" "$(yaml_get "$PROJECT_YAML" github_project 2>/dev/null)" "cancelled" \
+  "$(yaml_get "$PROJECT_YAML" assigned_to 2>/dev/null)" "$(yaml_get "$PROJECT_YAML" seeded_by 2>/dev/null)" "$BRANCH" || true
+
+# Close the GitHub Project board so a cancelled project stops reading as active (#56 Facet A).
+close_project_board "$GH_PROJECT"
+
+echo ""
+echo "=== Project cancelled."
+echo "    Status:              cancelled"
+echo "    cancelled_at:        $TODAY"
+echo "    cancellation_reason: $CANCELLATION_REASON"
+echo ""
+echo "    All code changes are preserved in archive tags (archive/$BRANCH)."
+echo "    No knowledge close was run."

package/scripts/close-knowledge.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+# Script: close-knowledge
+# Purpose: Synthesizes project knowledge into org knowledge proposals using LLM+RAG.
+#          Raises PR for domain owner review.
+# Usage:   bash close-knowledge.sh <project_id>
+# Triggered by: close-project automatically after successful project close.
+# Compliance: C02 (POL-097 to POL-106)
+#
+# LLM synthesis note:
+#   This script prepares the branch and context, then invokes the agent (Claude Code)
+#   to perform synthesis. The agent reads all project knowledge, queries relevant org
+#   knowledge, and proposes changes via the knowledge-close branch.
+#   If the agent is not available, the script falls back to creating the PR with raw
+#   project knowledge attached for manual review.
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+# ── Inputs ────────────────────────────────────────────────────────────────────
+
+PROJECT_ID="${1:-}"
+[[ -n "$PROJECT_ID" ]] || hard_stop "Usage: $0 <project_id>"
+
+echo "=== close-knowledge: $PROJECT_ID"
+echo ""
+
+PROJECT_YAML=$(get_project_yaml "$PROJECT_ID")
+PROJECT_DIR=$(get_project_dir "$PROJECT_ID")
+check_project_exists "$PROJECT_ID"
+
+# ── Pre-conditions ────────────────────────────────────────────────────────────
+
+require_project_status "$PROJECT_YAML" "completed"
+
+# The person closing knowledge must be authorized on the project — assigned_to
+# individual or a member of the assigned_to team (per-task/team model, POL-047).
+# Mirrors create-task.sh; closes the inconsistent-authz gap (#62/H9).
+CURRENT_USER=$(git config user.email 2>/dev/null || echo "")
+ASSIGNED_TO=$(yaml_get "$PROJECT_YAML" "assigned_to")        # display/audit cache
+GH_PROJECT=$(yaml_get "$PROJECT_YAML" "github_project")
+is_authorized_for_project "$GH_PROJECT" "$ASSIGNED_TO" \
+  || hard_stop "You ($CURRENT_USER) are not authorized on this project — you need write access to its GitHub Project ($GH_PROJECT)."
+
+KNOWLEDGE_DIR="$PROJECT_DIR/knowledge"
+if [[ ! -d "$KNOWLEDGE_DIR" ]] || [[ -z "$(find "$KNOWLEDGE_DIR" -type f 2>/dev/null)" ]]; then
+  hard_stop "projects/$PROJECT_ID/knowledge/ is empty — nothing to synthesize."
+fi
+
+BRANCH=$(project_branch_for_id "$PROJECT_ID")
+KNOWLEDGE_BRANCH="${BRANCH}-knowledge"
+TODAY=$(today)
+
+# ── Failure cleanup (#64) ─────────────────────────────────────────────────────
+# On any failure, undo the branch/temp-file this run created so a failed run
+# leaves no orphan branch or context file and is re-runnable. State flags are
+# flipped as each resource is created; _CK_DONE disarms the trap on success.
+KNOWLEDGE_SUMMARY_FILE="$REPO_ROOT/.close-knowledge-context-$PROJECT_ID.md"
+_CK_BRANCH_CREATED=false
+_CK_BRANCH_PUSHED=false
+_CK_DONE=false
+
+cleanup_on_failure() {
+  local rc=$?
+  $_CK_DONE && return 0
+  [[ $rc -eq 0 ]] && return 0
+  warn "close-knowledge failed (exit $rc) — cleaning up so the run is re-runnable."
+  rm -f "$KNOWLEDGE_SUMMARY_FILE" 2>/dev/null || true
+  if $_CK_BRANCH_CREATED; then
+    git -C "$REPO_ROOT" checkout "$DEFAULT_BRANCH" &>/dev/null || true
+    local scope="local"
+    if $_CK_BRANCH_PUSHED; then
+      git -C "$REPO_ROOT" push origin --delete "$KNOWLEDGE_BRANCH" &>/dev/null || true
+      scope="local + remote"
+    fi
+    git -C "$REPO_ROOT" branch -D "$KNOWLEDGE_BRANCH" &>/dev/null || true
+    info "Removed knowledge branch '$KNOWLEDGE_BRANCH' ($scope)."
+  fi
+}
+trap cleanup_on_failure EXIT
+
+# ── Create knowledge branch ───────────────────────────────────────────────────
+
+echo "Creating knowledge branch '$KNOWLEDGE_BRANCH'..."
+cd "$REPO_ROOT"
+git fetch origin "$DEFAULT_BRANCH"
+git checkout "$DEFAULT_BRANCH"
+git pull origin "$DEFAULT_BRANCH"
+
+if git rev-parse --verify "$KNOWLEDGE_BRANCH" &>/dev/null; then
+  hard_stop "Branch '$KNOWLEDGE_BRANCH' already exists — investigate before proceeding."
+fi
+git checkout -b "$KNOWLEDGE_BRANCH"
+_CK_BRANCH_CREATED=true
+
+# ── Collect project knowledge ─────────────────────────────────────────────────
+
+echo "Collecting project knowledge from $KNOWLEDGE_DIR..."
+
+{
+  echo "# Knowledge Close Context: $PROJECT_ID"
+  echo ""
+  echo "**Project:** $PROJECT_ID"
+  echo "**Closed:** $TODAY"
+  echo "**Knowledge dir:** projects/$PROJECT_ID/knowledge/"
+  echo ""
+  echo "---"
+  echo ""
+  echo "## Project Knowledge Files"
+  echo ""
+  find "$KNOWLEDGE_DIR" -type f | sort | while IFS= read -r f; do
+    rel="${f#$REPO_ROOT/}"
+    echo "### $rel"
+    echo ""
+    cat "$f"
+    echo ""
+    echo "---"
+    echo ""
+  done
+} > "$KNOWLEDGE_SUMMARY_FILE"
+
+info "Context written to: $KNOWLEDGE_SUMMARY_FILE"
+
+# ── LLM synthesis step ────────────────────────────────────────────────────────
+#
+# The agent (Claude Code) running this script MUST follow the Knowledge Harvest
+# Protocol — knowledge/development/procedures/knowledge-harvest.md (POL-413, C01):
+#   1. Reconstruct from EVIDENCE (git log -p across project repos, merged issues,
+#      todo.md, all projects/$PROJECT_ID/knowledge/ docs) — not from memory.
+#   2. Enumerate → classify (graduate/local/discard) every durable artifact; mine
+#      the non-obvious (gotchas, failures-and-fixes); journey review;
+#      completeness-critic pass.
+#   3. Write the manifest projects/$PROJECT_ID/knowledge/knowledge-close.md
+#      (template in the protocol). close-project's gate checks it is present +
+#      structurally complete (no TBD).
+#   4. Apply proposed org-knowledge changes to knowledge/ on this branch.
+#   5. Call: bash close-knowledge.sh <project_id> --finalize <pr_description_file>
+#
+# If the agent is not available, we fall back to attaching raw knowledge.
+
+if [[ "${2:-}" == "--finalize" ]]; then
+  # Phase 2: agent has done synthesis and calls us back to create the PR
+  PR_DESC_FILE="${3:-}"
+  [[ -n "$PR_DESC_FILE" && -f "$PR_DESC_FILE" ]] \
+    || hard_stop "--finalize requires a PR description file as argument 3."
+  PR_BODY=$(cat "$PR_DESC_FILE")
+  _finalize_mode=true
+else
+  # Phase 1: no agent synthesis — fall back to attaching raw knowledge for manual review
+  warn "LLM synthesis not performed — attaching raw project knowledge for manual review."
+  PR_BODY=$(cat <<MD
+## Knowledge Close: $PROJECT_ID
+
+**Automated synthesis was not performed.** This PR attaches the raw project knowledge
+for manual review by domain owners.
+
+### Project Knowledge
+
+See \`projects/$PROJECT_ID/knowledge/\` in this branch for all captured learnings.
+
+### Review Instructions
+
+Domain owners: please review the project knowledge and manually apply relevant
+learnings to the appropriate \`knowledge/\` subfolders in this PR.
+
+*Generated by close-knowledge.sh — fallback mode (no LLM synthesis)*
+MD
+)
+  _finalize_mode=false
+fi
+
+# ── Commit knowledge changes to branch ───────────────────────────────────────
+
+# Remove temp context file
+rm -f "$KNOWLEDGE_SUMMARY_FILE"
+
+# Stage any knowledge/ changes the agent may have made
+git add "framework/knowledge/" 2>/dev/null || true
+
+# If no changes were staged (fallback mode), there is nothing new to commit;
+# the PR will just carry the branch with existing org knowledge as baseline.
+if git diff --cached --quiet; then
+  info "No knowledge/ changes staged — PR will describe manual review needed."
+  # Create a placeholder note so the branch has at least one commit
+  mkdir -p "$REPO_ROOT/framework/knowledge/accumulated"
+  cat >> "$REPO_ROOT/framework/knowledge/accumulated/README.md" <<NOTE
+
+<!-- close-knowledge: $PROJECT_ID — manual review needed ($TODAY) -->
+NOTE
+  git add "framework/knowledge/accumulated/README.md"
+fi
+
+git commit -m "close-knowledge: $PROJECT_ID" --allow-empty
+git push -u origin "$KNOWLEDGE_BRANCH"
+_CK_BRANCH_PUSHED=true
+
+# ── Raise PR ──────────────────────────────────────────────────────────────────
+
+echo "Raising PR: $KNOWLEDGE_BRANCH → $DEFAULT_BRANCH..."
+
+PR_URL=$(gh pr create \
+  --base "$DEFAULT_BRANCH" \
+  --head "$KNOWLEDGE_BRANCH" \
+  --title "[Knowledge Close] $PROJECT_ID" \
+  --body "$PR_BODY" \
+  2>/dev/null) \
+  || {
+    warn "PR creation failed — retrying..."
+    PR_URL=$(gh pr create \
+      --base "$DEFAULT_BRANCH" \
+      --head "$KNOWLEDGE_BRANCH" \
+      --title "[Knowledge Close] $PROJECT_ID" \
+      --body "$PR_BODY")
+  }
+
+info "PR created: $PR_URL"
+
+# Point of no return: the branch is now referenced by a PR, so deleting it on a
+# later failure would orphan the PR. Disarm the branch/temp-file cleanup but
+# still drop the temp context file (which is removed earlier anyway).
+_CK_DONE=true
+rm -f "$KNOWLEDGE_SUMMARY_FILE" 2>/dev/null || true
+
+# ── Update project.yaml ───────────────────────────────────────────────────────
+
+cd "$REPO_ROOT"
+git checkout "$DEFAULT_BRANCH"
+git pull origin "$DEFAULT_BRANCH"
+
+yaml_set "$PROJECT_YAML" "knowledge_status" "pending_review"
+yaml_set "$PROJECT_YAML" "knowledge_pr"     "$PR_URL"
+
+git add "projects/$PROJECT_ID/project.yaml"
+git commit -m "close-knowledge: update knowledge_status for $PROJECT_ID"
+
+# Pre-push validation gate (rolls back commit if validators fail)
+validate_or_revert
+
+git push origin "$DEFAULT_BRANCH"
+
+echo ""
+echo "=== Knowledge close initiated."
+echo "    Branch:           $KNOWLEDGE_BRANCH"
+echo "    PR:               $PR_URL"
+echo "    knowledge_status: pending_review"
+echo ""
+echo "    CODEOWNERS will auto-assign domain reviewers."
+echo "    Outcome updates:"
+echo "      Merged   → archive tag + delete branch, knowledge_status: merged"
+echo "      Rejected → owner closes PR, knowledge_status: rejected"