@svayam-opensource/prj 0.5.1

package/scripts/merge-task.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# Script: merge-task
+# Purpose: Merges a completed sub-branch back into the project integration branch.
+#          Archives sub-branch. Closes the GitHub Issue(s) it covers.
+# Usage:   bash merge-task.sh <project_id> <issue_url | task_branch>
+#          arg2 may be a GitHub issue URL (single-issue task) OR the task
+#          sub-branch itself (BRANCH.ISSUE-<n1>-<n2>), which the work flow passes
+#          directly so combined multi-issue branches merge correctly (POL-070).
+# Compliance: C02 (POL-073 to POL-075)
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+# ── Inputs ────────────────────────────────────────────────────────────────────
+
+PROJECT_ID="${1:-}"
+TASK_ARG="${2:-}"
+
+[[ -n "$PROJECT_ID" ]] || hard_stop "Usage: $0 <project_id> <issue_url | task_branch>"
+[[ -n "$TASK_ARG"   ]] || hard_stop "Usage: $0 <project_id> <issue_url | task_branch>"
+
+echo "=== merge-task: $PROJECT_ID / $TASK_ARG"
+echo ""
+
+PROJECT_YAML=$(get_project_yaml "$PROJECT_ID")
+check_project_exists "$PROJECT_ID"
+
+# ── Pre-conditions ────────────────────────────────────────────────────────────
+
+require_project_status "$PROJECT_YAML" "active"
+
+# This op merges + pushes + archives branches + closes the issue — all mutating.
+# Gate it on GitHub-Project write access like the other mutating scripts
+# (create-task/seed/resume), per 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)."
+
+BRANCH=$(project_branch_for_id "$PROJECT_ID")
+
+# Resolve arg2 → the task sub-branch (TASK_ID) and every issue it closes.
+# Scheme B (POL-070): sub-branch = BRANCH.ISSUE-<n1>-<n2>-…, keyed on issue NUMBERS.
+#  - issue URL  → TASK_ID = BRANCH.ISSUE-<that number>; closes that one issue.
+#  - task branch → TASK_ID = the branch; closes every issue whose number it carries
+#    (resolved to a URL via the project board).
+ISSUE_URLS=()
+
+# resolve_board_issue_url <number> → the issue's URL on this project's board (or empty).
+resolve_board_issue_url() {
+  local want="$1" pnum powner
+  pnum=$(echo "$GH_PROJECT"   | grep -oE '/projects/[0-9]+' | grep -oE '[0-9]+')
+  powner=$(echo "$GH_PROJECT" | sed -E 's|.*/(orgs\|users)/([^/]+)/.*|\2|')
+  gh project item-list "$pnum" --owner "$powner" --format json --limit 200 2>/dev/null | python3 -c "
+import sys, json
+want = '$want'
+try: d = json.load(sys.stdin)
+except Exception: sys.exit(0)
+for i in d.get('items', []):
+    c = i.get('content') or {}
+    if str(c.get('number')) == want and c.get('url'):
+        print(c['url']); break
+"
+}
+
+if [[ "$TASK_ARG" == *"/issues/"* ]]; then
+  INUM=$(echo "$TASK_ARG" | grep -oE '/issues/[0-9]+' | grep -oE '[0-9]+$') \
+    || hard_stop "Could not parse an issue number from $TASK_ARG"
+  [[ -n "$INUM" ]] || hard_stop "Could not parse an issue number from $TASK_ARG"
+  TASK_ID="${BRANCH}.ISSUE-${INUM}"
+  ISSUE_URLS+=("$TASK_ARG")
+else
+  TASK_ID="$TASK_ARG"
+  [[ "$TASK_ID" == "${BRANCH}".ISSUE-* ]] \
+    || hard_stop "'$TASK_ID' is not a task sub-branch of '$BRANCH' (expected ${BRANCH}.ISSUE-<n>)."
+  SUFFIX="${TASK_ID#"${BRANCH}".ISSUE-}"
+  IFS='-' read -ra TASK_NUMS <<< "$SUFFIX"
+  for n in "${TASK_NUMS[@]}"; do
+    [[ "$n" =~ ^[0-9]+$ ]] || continue
+    u="$(resolve_board_issue_url "$n")"
+    if [[ -n "$u" ]]; then ISSUE_URLS+=("$u"); else warn "Could not resolve issue #$n on the board — close it manually after merge."; fi
+  done
+fi
+
+# Verify the task sub-branch exists on the remote
+git -C "$REPO_ROOT" ls-remote --exit-code --heads origin "$TASK_ID" >/dev/null 2>&1 \
+  || hard_stop "No sub-branch '$TASK_ID' on the remote — was the task created?"
+
+# Check no uncommitted changes in workspace
+check_clean "$REPO_ROOT"
+
+# Check no uncommitted changes in code repos
+while IFS= read -r repo_url; do
+  REPO_DIR="$(repo_clone_dir "$PROJECT_ID" "$(get_repo_name "$repo_url")")"
+  [[ -e "$REPO_DIR/.git" ]] && check_clean "$REPO_DIR"
+done < <(get_project_repos "$PROJECT_YAML")
+
+# ── Merge sub-branch into project branch ─────────────────────────────────────
+# Multi-repo, not transactional: a conflict on a later repo leaves earlier repos
+# already merged+pushed. To make a re-run safe (H5) we detect an already-merged
+# sub-branch with `git merge-base --is-ancestor` and skip it, and we defer ALL
+# archiving until every merge+push has succeeded — so a mid-loop failure never
+# archives some repos and not others.
+
+# Merge the sub-branch into the project branch in <path>, idempotently:
+# if $TASK_ID is already an ancestor of $BRANCH, the merge is a no-op and we skip
+# (no checkout/merge/push) so re-runs after a partial failure don't churn.
+merge_task_into_branch() {
+  local path="$1" label="$2"
+  git -C "$path" fetch origin "$TASK_ID" 2>/dev/null || true
+  if git -C "$path" merge-base --is-ancestor "$TASK_ID" "$BRANCH" 2>/dev/null; then
+    info "'$TASK_ID' already merged into '$BRANCH' in $label — skipping."
+    return 0
+  fi
+  echo "Merging '$TASK_ID' → '$BRANCH' in $label..."
+  merge_branch "$path" "$TASK_ID" "$BRANCH"
+  git -C "$path" push origin "$BRANCH"
+}
+
+cd "$REPO_ROOT"
+merge_task_into_branch "$REPO_ROOT" "workspace repo"
+
+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 — skipping merge."
+    continue
+  fi
+  merge_task_into_branch "$REPO_DIR" "$REPO_NAME"
+done < <(get_project_repos "$PROJECT_YAML")
+
+# Reaching here means every merge+push above succeeded (merge_branch exits 2 on
+# conflict). Only now is it safe to archive sub-branches across all repos.
+
+# ── Archive sub-branches ──────────────────────────────────────────────────────
+
+echo ""
+echo "Archiving sub-branches..."
+
+archive_branch "$REPO_ROOT" "$TASK_ID"
+
+while IFS= read -r repo_url; do
+  REPO_DIR="$(repo_clone_dir "$PROJECT_ID" "$(get_repo_name "$repo_url")")"
+  [[ -e "$REPO_DIR/.git" ]] && archive_branch "$REPO_DIR" "$TASK_ID"
+done < <(get_project_repos "$PROJECT_YAML")
+
+# ── Close every GitHub Issue the branch covers + mark Done on the board ───────
+GHPROJ=$(yaml_get "$PROJECT_YAML" "github_project")
+for u in "${ISSUE_URLS[@]}"; do
+  gh issue close "$u" --comment "Task \`$TASK_ID\` merged into \`$BRANCH\`." 2>/dev/null \
+    || warn "Could not close issue $u — close manually."
+  info "Closed issue: $u"
+  board_set_status "$GHPROJ" "$u" "Done" || true
+done
+
+echo ""
+echo "=== Task merged successfully!"
+echo "    Task:    $TASK_ID"
+echo "    Merged → $BRANCH"
+echo "    Issues:  ${ISSUE_URLS[*]:-n/a} (closed)"

package/scripts/onboard-repo.sh

@@ -0,0 +1,275 @@
+#!/usr/bin/env bash
+# Script: onboard-repo
+# Purpose: Initializes the knowledge/ folder structure in an existing code repo,
+#          bringing it under the Agentic Development Policy.
+# Usage:   bash onboard-repo.sh <repo_url> <repo_description> <repo_owner>
+# Compliance: C02 — repo owner must approve the PR (POL-108)
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+# ── Inputs ────────────────────────────────────────────────────────────────────
+
+REPO_URL="${1:-}"
+REPO_DESC="${2:-}"
+REPO_OWNER="${3:-}"
+
+[[ -n "$REPO_URL"   ]] || hard_stop "Usage: $0 <repo_url> <repo_description> <repo_owner>"
+[[ -n "$REPO_DESC"  ]] || hard_stop "Usage: $0 <repo_url> <repo_description> <repo_owner>"
+[[ -n "$REPO_OWNER" ]] || hard_stop "Usage: $0 <repo_url> <repo_description> <repo_owner>"
+
+REPO_NAME=$(get_repo_name "$REPO_URL")
+ONBOARD_BRANCH="onboard-knowledge"
+
+echo "=== onboard-repo: $REPO_URL"
+echo "    Description: $REPO_DESC"
+echo "    Owner:       $REPO_OWNER"
+echo ""
+
+# ── Clone or locate repo ──────────────────────────────────────────────────────
+
+TMP_CLONE=false
+# #65/H6: $PRJ_GOV_LOC was never defined → aborted under `set -u`. Use the
+# resolved AGENT_WORK_ROOT (set by load_config), matching seed.sh/join.sh.
+REPO_DIR="$AGENT_WORK_ROOT/onboard/$REPO_NAME"
+
+if [[ -e "$REPO_DIR/.git" ]]; then
+  info "Found existing clone at $REPO_DIR — fetching..."
+  git -C "$REPO_DIR" fetch origin
+else
+  info "Cloning $REPO_URL → $REPO_DIR..."
+  mkdir -p "$AGENT_WORK_ROOT/onboard"
+  git clone "$REPO_URL" "$REPO_DIR" || hard_stop "Clone failed for $REPO_URL — verify access."
+  TMP_CLONE=true
+fi
+
+# Detect default branch
+REPO_DEFAULT_BRANCH=$(git -C "$REPO_DIR" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
+  | sed 's|refs/remotes/origin/||') || REPO_DEFAULT_BRANCH="main"
+
+# ── Pre-conditions ────────────────────────────────────────────────────────────
+
+if [[ -d "$REPO_DIR/knowledge" ]]; then
+  hard_stop "knowledge/ already exists in $REPO_NAME — investigate existing structure."
+fi
+
+if git -C "$REPO_DIR" ls-remote --exit-code origin "$ONBOARD_BRANCH" &>/dev/null; then
+  hard_stop "Branch '$ONBOARD_BRANCH' already exists in $REPO_NAME — investigate before proceeding."
+fi
+
+# ── Create onboard-knowledge branch ──────────────────────────────────────────
+
+git -C "$REPO_DIR" checkout "$REPO_DEFAULT_BRANCH"
+git -C "$REPO_DIR" pull origin "$REPO_DEFAULT_BRANCH" 2>/dev/null || true
+git -C "$REPO_DIR" checkout -b "$ONBOARD_BRANCH"
+
+# ── Scaffold knowledge/ folder ────────────────────────────────────────────────
+
+mkdir -p "$REPO_DIR/knowledge/repo"
+
+# knowledge/agent.md — from repo-agent-template
+cat > "$REPO_DIR/knowledge/agent.md" <<MD
+# $REPO_NAME — Agent Entry Point
+
+**Repository:** $REPO_URL
+**Purpose:** $REPO_DESC
+**Owner:** $REPO_OWNER
+
+---
+
+## Important: Knowledge Layer Priority
+
+This file represents the **repo-local knowledge layer** — third priority.
+
+\`\`\`
+1. Org-wide knowledge      → $WORKSPACE_REPO/knowledge/        [HIGHEST]
+2. Project knowledge       → $WORKSPACE_REPO/projects/<project-id>/knowledge/
+3. This repo's knowledge   → this file and knowledge/repo/      [THIS FILE]
+4. Your developer prefs    → $AGENT_WORK_ROOT/preferences/<your-gh-login>.md
+\`\`\`
+
+**This file cannot override org-wide knowledge or policy.**
+See \`$WORKSPACE_REPO/knowledge/policies/agentic-development-policy.md\`.
+
+---
+
+## Repo Knowledge
+
+Read the following before working in this repository:
+
+- \`knowledge/repo/structure.md\`   — directory layout, modules, packages
+- \`knowledge/repo/environment.md\` — build tools, dependencies, setup instructions
+- \`knowledge/repo/patterns.md\`    — coding conventions, architectural patterns
+
+---
+
+## Write Restrictions
+
+During an active project:
+- Do NOT modify \`knowledge/repo/\` directly
+- All knowledge writes go to \`$WORKSPACE_REPO/projects/<project-id>/knowledge/\`
+- Repo knowledge is updated only via the project's knowledge close PR
+
+---
+
+## Data Classification Reminder
+
+Never commit credentials, secrets, API keys, or PII (C01).
+See \`$WORKSPACE_REPO/knowledge/policies/data-classification.md\`.
+MD
+
+# knowledge/repo/structure.md — placeholder
+cat > "$REPO_DIR/knowledge/repo/structure.md" <<MD
+# $REPO_NAME — Repository Structure
+
+**Owner:** $REPO_OWNER
+**TODO:** Populate this file with the repository's directory layout.
+
+---
+
+## Directory Layout
+
+\`\`\`
+<describe the top-level directories and their purpose>
+\`\`\`
+
+## Key Modules / Packages
+
+- \`<module>\` — <description>
+
+## Entry Points
+
+- \`<main file or command>\` — <description>
+MD
+
+# knowledge/repo/environment.md — placeholder
+cat > "$REPO_DIR/knowledge/repo/environment.md" <<MD
+# $REPO_NAME — Environment & Setup
+
+**Owner:** $REPO_OWNER
+**TODO:** Populate this file with build tools, dependencies, and local setup.
+
+---
+
+## Prerequisites
+
+- <tool> <version>
+- <tool> <version>
+
+## Local Setup
+
+\`\`\`bash
+# Steps to get this repo running locally
+\`\`\`
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| \`ENV_VAR\` | Yes | Description |
+
+## Running Tests
+
+\`\`\`bash
+# How to run the test suite
+\`\`\`
+MD
+
+# knowledge/repo/patterns.md — placeholder
+cat > "$REPO_DIR/knowledge/repo/patterns.md" <<MD
+# $REPO_NAME — Patterns & Conventions
+
+**Owner:** $REPO_OWNER
+**TODO:** Populate this file with coding conventions and architectural patterns.
+
+---
+
+## Coding Style
+
+- Language: <language>
+- Linter / formatter: <tool>
+- Key conventions: <describe>
+
+## Architectural Patterns
+
+- <pattern name>: <description>
+
+## Common Pitfalls
+
+- <pitfall>: <how to avoid>
+MD
+
+info "Scaffolded knowledge/ folder."
+
+# ── Commit and push ───────────────────────────────────────────────────────────
+
+git -C "$REPO_DIR" add knowledge/
+git -C "$REPO_DIR" commit -m "onboard: initialize knowledge/ folder for agentic development"
+git -C "$REPO_DIR" push -u origin "$ONBOARD_BRANCH" \
+  || hard_stop "Push failed for $REPO_URL — verify push access."
+
+info "Branch '$ONBOARD_BRANCH' pushed."
+
+# ── Raise PR ──────────────────────────────────────────────────────────────────
+
+echo "Raising PR..."
+
+PR_BODY=$(cat <<MD
+## [Onboard] Initialize \`knowledge/\` folder for agentic development
+
+This PR adds the \`knowledge/\` folder structure to bring **$REPO_NAME** under the
+$ORG_NAME Agentic Development Policy.
+
+### What was added
+
+- \`knowledge/agent.md\` — agent entry point with knowledge layer priority
+- \`knowledge/repo/structure.md\` — placeholder for repo structure
+- \`knowledge/repo/environment.md\` — placeholder for build/setup instructions
+- \`knowledge/repo/patterns.md\` — placeholder for coding conventions
+
+### What the repo owner needs to do after merging
+
+Please populate the placeholder files with accurate information:
+
+1. **\`knowledge/repo/structure.md\`** — describe the directory layout and key modules
+2. **\`knowledge/repo/environment.md\`** — document build tools, env vars, setup steps
+3. **\`knowledge/repo/patterns.md\`** — document coding conventions and architectural patterns
+
+Submit these as a follow-up PR directly in this repo.
+
+### What this PR does NOT do
+
+- Does not modify CI/CD pipelines
+- Does not add application code
+- Does not enforce any structural changes beyond adding \`knowledge/\`
+
+*Generated by onboard-repo.sh*
+MD
+)
+
+PR_URL=$(gh pr create \
+  --repo "$REPO_URL" \
+  --base "$REPO_DEFAULT_BRANCH" \
+  --head "$ONBOARD_BRANCH" \
+  --title "[Onboard] Initialize knowledge/ folder for agentic development" \
+  --body "$PR_BODY" \
+  2>/dev/null) \
+  || {
+    warn "PR creation failed — retrying..."
+    PR_URL=$(gh pr create \
+      --repo "$REPO_URL" \
+      --base "$REPO_DEFAULT_BRANCH" \
+      --head "$ONBOARD_BRANCH" \
+      --title "[Onboard] Initialize knowledge/ folder for agentic development" \
+      --body "$PR_BODY")
+  }
+
+echo ""
+echo "=== Onboarding PR created!"
+echo "    PR:   $PR_URL"
+echo ""
+echo "    After the repo owner merges this PR, they should populate:"
+echo "    - knowledge/repo/structure.md"
+echo "    - knowledge/repo/environment.md"
+echo "    - knowledge/repo/patterns.md"

package/scripts/pause.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Script: pause
+# Purpose: Transitions a project from ACTIVE to PAUSED.
+#          Preserves all state for later resumption.
+# Usage:   bash pause.sh <project_id>
+# Compliance: C02 (POL-049, POL-051)
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+# ── Inputs ────────────────────────────────────────────────────────────────────
+
+PROJECT_ID="${1:-}"
+[[ -n "$PROJECT_ID" ]] || hard_stop "Usage: $0 <project_id>"
+
+echo "=== pause: $PROJECT_ID"
+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 to pause — '$CURRENT_USER' needs write access to the project's GitHub Project ($GH_PROJECT)."
+
+BRANCH=$(project_branch_for_id "$PROJECT_ID")
+
+echo "Checking for uncommitted changes..."
+
+check_clean "$REPO_ROOT"
+
+while IFS= read -r repo_url; do
+  REPO_DIR="$(repo_clone_dir "$PROJECT_ID" "$(get_repo_name "$repo_url")")"
+  [[ -e "$REPO_DIR/.git" ]] && check_clean "$REPO_DIR"
+done < <(get_project_repos "$PROJECT_YAML")
+
+info "All repos are clean."
+
+# ── Update project.yaml ───────────────────────────────────────────────────────
+
+TODAY=$(today)
+yaml_set "$PROJECT_YAML" "status"    "paused"
+yaml_set "$PROJECT_YAML" "paused_at" "$TODAY"
+
+# ── Push all branches ─────────────────────────────────────────────────────────
+
+cd "$REPO_ROOT"
+git checkout "$BRANCH"
+git add "projects/$PROJECT_ID/project.yaml"
+git commit -m "pause: $PROJECT_ID"
+git push origin "$BRANCH"
+
+while IFS= read -r repo_url; do
+  REPO_DIR="$(repo_clone_dir "$PROJECT_ID" "$(get_repo_name "$repo_url")")"
+  if [[ -e "$REPO_DIR/.git" ]]; then
+    git -C "$REPO_DIR" push origin "$BRANCH" 2>/dev/null || warn "Push skipped for $repo_url (nothing to push)"
+  fi
+done < <(get_project_repos "$PROJECT_YAML")
+
+# ── Reflect pause in the registry index on the default branch + README mirror ─
+# project.yaml status lives on the project branch; the authoritative index lives
+# on $DEFAULT_BRANCH. Flip it so `prj list`/`prj status` don't show a paused
+# project as active.
+registry_set_status_on_main "$PROJECT_ID" "paused"
+project_readme_mirror "$PROJECT_ID" "$(yaml_get "$PROJECT_YAML" github_project)" "paused" \
+  "$(yaml_get "$PROJECT_YAML" assigned_to)" "$(yaml_get "$PROJECT_YAML" seeded_by)" "$BRANCH" || true
+
+echo ""
+echo "=== Project paused."
+echo "    Status:    paused"
+echo "    paused_at: $TODAY"
+echo ""
+echo "    Resume with: bash resume.sh $PROJECT_ID"

package/scripts/project-access.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Script: project-access
+# Purpose: Grant or revoke WRITE access on a GitHub Project v2 — the ADR-0001
+#          Phase 3 source of truth for assignment (access = authorization).
+#          Wraps lib.sh's gh_* helpers so the prj CLI (which does not source
+#          lib.sh) can sync GitHub access from `manage assign/unassign/reassign`.
+# Usage:   bash project-access.sh <grant|revoke> <github_project_url> <login-or-@team>
+# Note:    MUTATES real GitHub Project permissions.
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+ACTION="${1:-}"; URL="${2:-}"; WHO="${3:-}"
+[[ -n "$ACTION" && -n "$URL" && -n "$WHO" ]] \
+  || hard_stop "Usage: $0 <grant|revoke> <github_project_url> <login-or-@team>"
+
+case "$ACTION" in
+  grant)  ROLE=WRITER ;;
+  revoke) ROLE=NONE ;;
+  *)      hard_stop "Unknown action '$ACTION' (expected grant|revoke)." ;;
+esac
+
+PROJ_ID=$(gh_project_node_id "$URL") \
+  || hard_stop "Could not resolve a GitHub Project from '$URL' (check access / token scopes)."
+
+ACTOR=$(gh_resolve_actor "$WHO") \
+  || hard_stop "Could not resolve '$WHO' to a GitHub user or team. Use a GitHub login, or '@team-slug'."
+read -r KIND AID <<< "$ACTOR"
+
+if gh_project_set_access "$PROJ_ID" "$KIND" "$AID" "$ROLE"; then
+  info "GitHub Project access: ${ACTION}ed '$WHO' ($KIND) — role $ROLE."
+else
+  hard_stop "GitHub API call failed. Set access manually in the Project's Manage access."
+fi