@svayam-opensource/prj 0.5.1

package/scripts/propose-knowledge.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# Script: propose-knowledge
+# Purpose: Ad-hoc org knowledge proposals outside any project context.
+#          Used for initial bootstrap, policy updates, and standalone learnings.
+# Usage:   bash propose-knowledge.sh <branch_slug> <description>
+# Compliance: C02 — proposals require domain owner approval via PR (POL-107 to POL-109)
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+# ── Inputs ────────────────────────────────────────────────────────────────────
+
+BRANCH_SLUG="${1:-}"
+DESCRIPTION="${2:-}"
+MODE="${3:-create}"   # create (default), --submit, --archive
+
+[[ -n "$BRANCH_SLUG"  ]] || hard_stop "Usage: $0 <branch_slug> <description> [--submit|--archive]"
+[[ -n "$DESCRIPTION"  ]] || hard_stop "Usage: $0 <branch_slug> <description> [--submit|--archive]"
+
+case "$MODE" in
+  create|--submit|--archive) ;;
+  *) hard_stop "Unknown mode: $MODE (expected --submit or --archive)" ;;
+esac
+
+KNOWLEDGE_BRANCH="knowledge-$BRANCH_SLUG"
+
+echo "=== propose-knowledge"
+echo "    Branch:      $KNOWLEDGE_BRANCH"
+echo "    Description: $DESCRIPTION"
+echo "    Mode:        $MODE"
+echo ""
+
+cd "$REPO_ROOT"
+git fetch origin "$DEFAULT_BRANCH" 2>/dev/null || true
+git fetch origin "$KNOWLEDGE_BRANCH" 2>/dev/null || true
+
+# ── Mode: create ──────────────────────────────────────────────────────────────
+
+if [[ "$MODE" == "create" ]]; then
+  if git rev-parse --verify "$KNOWLEDGE_BRANCH" &>/dev/null || \
+     git ls-remote --exit-code origin "$KNOWLEDGE_BRANCH" &>/dev/null; then
+    hard_stop "Branch '$KNOWLEDGE_BRANCH' already exists — investigate before proceeding."
+  fi
+
+  # Failure cleanup (#64): if branch creation/push fails part-way (e.g. push
+  # rejected after the local branch exists), undo what we made so a re-run does
+  # not hard-stop on "branch already exists". State flags gate each undo; the
+  # trap is disarmed once create mode completes successfully.
+  _PK_BRANCH_CREATED=false
+  _PK_BRANCH_PUSHED=false
+  _PK_DONE=false
+  cleanup_on_failure() {
+    local rc=$?
+    $_PK_DONE && return 0
+    [[ $rc -eq 0 ]] && return 0
+    warn "propose-knowledge failed (exit $rc) — cleaning up so the run is re-runnable."
+    if $_PK_BRANCH_CREATED; then
+      git -C "$REPO_ROOT" checkout "$DEFAULT_BRANCH" &>/dev/null || true
+      local scope="local"
+      if $_PK_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 branch '$KNOWLEDGE_BRANCH' ($scope)."
+    fi
+  }
+  trap cleanup_on_failure EXIT
+
+  git checkout "$DEFAULT_BRANCH"
+  git pull origin "$DEFAULT_BRANCH"
+  git checkout -b "$KNOWLEDGE_BRANCH"
+  _PK_BRANCH_CREATED=true
+  git push -u origin "$KNOWLEDGE_BRANCH"
+  _PK_BRANCH_PUSHED=true
+
+  echo "Branch '$KNOWLEDGE_BRANCH' created."
+  echo ""
+  echo "=== Next: Author your knowledge changes"
+  echo ""
+  echo "    1. Edit or add files under knowledge/ on branch '$KNOWLEDGE_BRANCH'."
+  echo "       - New content:     add to the owning domain's layer (see knowledge/README.md)"
+  echo "       - Policy updates:  edit knowledge/policies/"
+  echo "       - Patterns:        edit <domain>/patterns/"
+  echo "       - Architecture:    edit knowledge/architecture/{system,data}/"
+  echo ""
+  echo "    2. Commit your changes:"
+  echo "       git add knowledge/"
+  echo "       git commit -m 'knowledge: $DESCRIPTION'"
+  echo "       git push origin $KNOWLEDGE_BRANCH"
+  echo ""
+  echo "    3. Then create the PR:"
+  echo "       bash propose-knowledge.sh $BRANCH_SLUG \"$DESCRIPTION\" --submit"
+  echo ""
+  # Success: branch is intentionally kept for the author — disarm cleanup.
+  _PK_DONE=true
+  exit 0
+fi
+
+# ── Mode: --submit / --archive — branch must already exist ───────────────────
+
+if ! git rev-parse --verify "$KNOWLEDGE_BRANCH" &>/dev/null && \
+   ! git ls-remote --exit-code origin "$KNOWLEDGE_BRANCH" &>/dev/null; then
+  hard_stop "Branch '$KNOWLEDGE_BRANCH' does not exist. Run without --submit/--archive first to create it."
+fi
+
+if [[ "$MODE" == "--submit" ]]; then
+  # ── Raise PR ────────────────────────────────────────────────────────────────
+  echo "Creating PR: $KNOWLEDGE_BRANCH → $DEFAULT_BRANCH..."
+
+  PR_BODY=$(cat <<MD
+## Knowledge Proposal: $DESCRIPTION
+
+**Branch:** \`$KNOWLEDGE_BRANCH\`
+**Author:** $(git config user.email 2>/dev/null || echo "unknown")
+**Date:** $(today)
+
+### Summary
+
+$DESCRIPTION
+
+### Review Notes
+
+- This is a manually authored knowledge proposal (no LLM synthesis).
+- CODEOWNERS will auto-assign domain owners as reviewers based on folders touched.
+- Once merged, CI/CD will regenerate static site and vector embeddings.
+
+### Post-merge
+
+Archive tag \`archive/$KNOWLEDGE_BRANCH\` will be created and branch deleted.
+
+*Generated by propose-knowledge.sh*
+MD
+)
+
+  PR_URL=$(gh pr create \
+    --base "$DEFAULT_BRANCH" \
+    --head "$KNOWLEDGE_BRANCH" \
+    --title "[Knowledge Proposal] $DESCRIPTION" \
+    --body "$PR_BODY" \
+    2>/dev/null) \
+    || {
+      warn "PR creation failed — retrying..."
+      PR_URL=$(gh pr create \
+        --base "$DEFAULT_BRANCH" \
+        --head "$KNOWLEDGE_BRANCH" \
+        --title "[Knowledge Proposal] $DESCRIPTION" \
+        --body "$PR_BODY")
+    }
+
+  echo ""
+  echo "=== PR created: $PR_URL"
+  echo "    CODEOWNERS will auto-assign domain reviewers."
+  echo ""
+  echo "    After merge, archive the branch:"
+  echo "    bash propose-knowledge.sh $BRANCH_SLUG \"$DESCRIPTION\" --archive"
+fi
+
+if [[ "$MODE" == "--archive" ]]; then
+  # ── Archive after merge ──────────────────────────────────────────────────────
+  git fetch origin "$DEFAULT_BRANCH"
+  git checkout "$DEFAULT_BRANCH"
+  git pull origin "$DEFAULT_BRANCH"
+  archive_branch "$REPO_ROOT" "$KNOWLEDGE_BRANCH"
+  echo ""
+  echo "=== Branch archived: archive/$KNOWLEDGE_BRANCH"
+fi

package/scripts/release-to-public.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# scripts/release-to-public.sh
+#
+# Cuts a new release of the Agentic Development Framework from the publish
+# branch. The release process is:
+#
+#   1. Run the end-to-end smoke test (gate — non-bypassable except by
+#      explicit confirmation).
+#   2. Verify we're on publish, clean, and up to date with origin.
+#   3. Tag publish at HEAD with the requested version.
+#   4. Push the tag to origin (this updates the public template repo's
+#      releases page).
+#
+# Usage:
+#   bash scripts/release-to-public.sh vX.Y.Z
+#   bash scripts/release-to-public.sh --skip-smoke vX.Y.Z   # emergency only
+#
+# Run this from the publish branch. The script will refuse to run from
+# any other branch.
+#
+# After this script succeeds, the maintainer still needs to:
+#   - sync publish → main (bash scripts/sync-from-publish.sh)
+#   - push publish to the public template repo at
+#     svayam-opensource/governed-agentic-dev-framework
+
+set -uo pipefail
+
+# ── Output helpers (self-contained — we don't source lib.sh because on the
+# publish branch, org-config.yaml ships with empty values which would trip
+# lib.sh's load_config) ──────────────────────────────────────────────────────
+
+BOLD='\033[1m'; CYAN='\033[0;36m'; GREEN='\033[0;32m'; RED='\033[0;31m'; YELLOW='\033[1;33m'; NC='\033[0m'
+info()      { echo -e "${CYAN}  →${NC} $*"; }
+ok()        { echo -e "${GREEN}  ✓${NC} $*"; }
+warn()      { echo -e "${YELLOW}  !${NC} $*" >&2; }
+err()       { echo -e "${RED}  ✗${NC} $*" >&2; }
+header()    { echo ""; echo -e "${BOLD}${CYAN}$*${NC}"; }
+hard_stop() { err "$*"; exit 1; }
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# ── Flag parsing ──────────────────────────────────────────────────────────────
+
+SKIP_SMOKE=false
+VERSION=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --skip-smoke) SKIP_SMOKE=true ;;
+    -h|--help)
+      grep '^# ' "$0" | sed 's/^# //;s/^#//' | head -30
+      exit 0
+      ;;
+    v*.*.*) VERSION="$1" ;;
+    *) hard_stop "Unknown arg: $1 (expected vX.Y.Z or --skip-smoke)" ;;
+  esac
+  shift
+done
+
+[[ -n "$VERSION" ]] || hard_stop "Missing version. Usage: bash $0 vX.Y.Z"
+
+# Validate semver shape
+[[ "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] \
+  || hard_stop "Version '$VERSION' is not a vX.Y.Z semver tag."
+
+# ── Pre-conditions ────────────────────────────────────────────────────────────
+
+cd "$REPO_ROOT"
+
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+[[ "$CURRENT_BRANCH" == "publish" ]] \
+  || hard_stop "Run from 'publish' (currently on '$CURRENT_BRANCH')."
+
+[[ -z "$(git status --porcelain)" ]] \
+  || hard_stop "Uncommitted changes present. Commit or stash first."
+
+if git rev-parse --verify "refs/tags/$VERSION" >/dev/null 2>&1; then
+  hard_stop "Tag '$VERSION' already exists locally. Pick a higher version."
+fi
+
+if git ls-remote --exit-code --tags origin "refs/tags/$VERSION" >/dev/null 2>&1; then
+  hard_stop "Tag '$VERSION' already exists on origin. Pick a higher version."
+fi
+
+# ── Version-consistency + monotonic-release guard ─────────────────────────────
+# The tag must match framework/VERSION and never be lower than the latest release.
+FW_VER="$(cat "$REPO_ROOT/framework/VERSION" 2>/dev/null | tr -d '[:space:]')"
+if [[ -n "$FW_VER" && "${VERSION#v}" != "$FW_VER" ]]; then
+  hard_stop "Release tag $VERSION != framework/VERSION ($FW_VER). Bump framework/VERSION or fix the tag."
+fi
+LAST_TAG="$(git tag -l 'v*.*.*' | sort -V | tail -n1)"
+if [[ -n "$LAST_TAG" ]]; then
+  LO="$(printf '%s\n%s\n' "${VERSION#v}" "${LAST_TAG#v}" | sort -V | head -n1)"
+  if [[ "$LO" == "${VERSION#v}" && "${VERSION#v}" != "${LAST_TAG#v}" ]]; then
+    hard_stop "Release $VERSION is LOWER than the latest release $LAST_TAG — refusing a non-monotonic release."
+  fi
+fi
+
+# Verify git identity is set — tag creation needs it. Fail fast here rather
+# than after a 3-minute smoke run.
+GIT_NAME=$(git config user.name 2>/dev/null || echo "")
+GIT_MAIL=$(git config user.email 2>/dev/null || echo "")
+if [[ -z "$GIT_NAME" || -z "$GIT_MAIL" ]] \
+   && [[ -z "${GIT_COMMITTER_NAME:-}" || -z "${GIT_COMMITTER_EMAIL:-}" ]]; then
+  hard_stop "git user.name/user.email not configured (and GIT_COMMITTER_* not in env).
+    Set them before tagging:
+      git config user.name 'Your Name'
+      git config user.email 'you@example.com'
+    Or export GIT_COMMITTER_NAME + GIT_COMMITTER_EMAIL (and the matching GIT_AUTHOR_*)
+    in your shell, then re-run this script."
+fi
+
+info "Fetching latest from origin..."
+git fetch origin publish --tags >/dev/null 2>&1 \
+  || hard_stop "git fetch failed"
+
+LOCAL_SHA=$(git rev-parse HEAD)
+REMOTE_SHA=$(git rev-parse origin/publish)
+[[ "$LOCAL_SHA" == "$REMOTE_SHA" ]] \
+  || hard_stop "Local publish ($LOCAL_SHA) is not in sync with origin/publish ($REMOTE_SHA). Push or pull first."
+
+ok "on publish, clean, in sync with origin"
+
+# ── Phase 1: smoke gate ──────────────────────────────────────────────────────
+
+header "Release gate: end-to-end smoke test"
+
+if $SKIP_SMOKE; then
+  warn "WARNING: --skip-smoke specified. The smoke test gates exist to catch"
+  warn "regressions that the per-test suites do not. Skipping is for emergencies"
+  warn "(e.g., the smoke fixture itself is broken upstream). The last 4 releases"
+  warn "all needed hotfix-on-hotfix because we shipped without this gate."
+  echo ""
+  read -p "  Type 'SKIP-SMOKE' verbatim to confirm bypass: " confirm
+  [[ "$confirm" == "SKIP-SMOKE" ]] || hard_stop "Bypass not confirmed. Aborting."
+  warn "Smoke skipped by maintainer confirmation."
+else
+  info "Running tests/e2e_smoke.sh --always-clean..."
+  echo ""
+  bash "$REPO_ROOT/tests/e2e_smoke.sh" --always-clean \
+    || hard_stop "Smoke test failed. Fix the regression before releasing $VERSION."
+  ok "smoke passed"
+fi
+
+# ── Phase 2: tag publish ──────────────────────────────────────────────────────
+
+header "Tagging $VERSION on publish at $LOCAL_SHA"
+
+git tag -a "$VERSION" -m "Release $VERSION
+
+Tagged via scripts/release-to-public.sh from publish branch.
+Smoke test: $($SKIP_SMOKE && echo 'SKIPPED (maintainer override)' || echo 'passed')
+" \
+  || hard_stop "git tag failed"
+ok "tag $VERSION created locally"
+
+# ── Phase 3: push tag to origin ──────────────────────────────────────────────
+
+info "Pushing tag $VERSION to origin..."
+if git push origin "$VERSION" >/dev/null 2>&1; then
+  ok "tag pushed to origin"
+else
+  err "git push origin $VERSION failed."
+  err "The tag exists locally but isn't published. To recover:"
+  err "  git tag -d $VERSION                  # remove local tag, then retry"
+  err "  bash scripts/release-to-public.sh $VERSION"
+  exit 1
+fi
+
+# ── Done ──────────────────────────────────────────────────────────────────────
+
+echo ""
+echo -e "${BOLD}${GREEN}✓ Released $VERSION${NC}"
+echo ""
+echo "Next steps for the maintainer:"
+echo "  1. Sync publish → main:"
+echo "       git checkout main"
+echo "       bash scripts/sync-from-publish.sh"
+echo ""
+echo "  2. Mirror publish to the public template repo:"
+echo "       (run your mirror script, or push publish + tag to the public remote)"
+echo ""
+echo "  3. (Optional) Create a GitHub Release on the public repo:"
+echo "       gh release create $VERSION --notes-from-tag --repo svayam-opensource/governed-agentic-dev-framework"
+echo ""

package/scripts/render-harness.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# Script: render-harness
+# Purpose: Render per-tool agent entrypoints from the ONE canonical protocol so
+#          they never drift. Source of truth:
+#            - agent/session-protocol.md     (the protocol body)
+#            - agent/harness-manifest.yaml    (which tools, paths, templates, tiers)
+#          Regenerates every harness with generated:true and status:active.
+#          CLAUDE.md (import tier, generated:false) is hand-maintained and never
+#          overwritten — it @imports the canonical files instead.
+# Usage:
+#   bash render-harness.sh                  # (re)render all generated root files
+#   bash render-harness.sh --check          # verify on-disk files match; exit 1 on drift (CI gate)
+#   bash render-harness.sh --list           # list every registered harness + tier + status
+#   bash render-harness.sh --project <PID>  # write per-project entrypoints under projects/<PID>/
+# Compliance: keeps the POL-113..117 protocol single-sourced (one edit, re-render).
+
+set -euo pipefail
+
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+MANIFEST="$REPO/agent/harness-manifest.yaml"
+PROTOCOL="$REPO/agent/session-protocol.md"
+ENTRYPOINT="$REPO/framework/agent.md"
+
+[[ -f "$MANIFEST" ]] || { echo "ERROR: manifest not found: $MANIFEST" >&2; exit 1; }
+[[ -f "$PROTOCOL" ]] || { echo "ERROR: canonical protocol not found: $PROTOCOL" >&2; exit 1; }
+command -v python3 >/dev/null 2>&1 || { echo "ERROR: python3 is required" >&2; exit 1; }
+
+MODE="render"; PID=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --check)   MODE="check" ;;
+    --list)    MODE="list" ;;
+    --project) MODE="project"; PID="${2:-}"; shift; [[ -n "$PID" ]] || { echo "ERROR: --project needs a <PID>" >&2; exit 1; } ;;
+    -h|--help) sed -n '2,20p' "$0"; exit 0 ;;
+    *) echo "ERROR: unknown argument: $1" >&2; exit 1 ;;
+  esac
+  shift
+done
+
+python3 - "$MANIFEST" "$PROTOCOL" "$ENTRYPOINT" "$REPO" "$MODE" "$PID" <<'PY'
+import sys, os, yaml
+
+manifest_path, protocol_path, entrypoint_path, repo, mode, pid = sys.argv[1:7]
+
+M = yaml.safe_load(open(manifest_path)) or {}
+banner = (M.get("generated_banner") or "").strip()
+templates = M.get("templates", {}) or {}
+harnesses = M.get("harnesses", []) or []
+body = open(protocol_path).read().rstrip("\n")
+
+def subst(tmpl, mapping, extra=None):
+    out = tmpl
+    # Render markers are namespaced ({{render.X}} / {{template_extra.X}}) so the
+    # dot keeps them out of the org-placeholder regex ({{NAME}}, no dots), which
+    # setup.sh substitutes and STRICT_PLACEHOLDERS validates.
+    for k, v in mapping.items():
+        out = out.replace("{{render.%s}}" % k, v)
+    for k, v in (extra or {}).items():
+        sv = "true" if v is True else "false" if v is False else str(v)
+        out = out.replace("{{template_extra.%s}}" % k, sv)
+    return out.rstrip("\n") + "\n"
+
+def render_file(harness, body_text):
+    """Render one harness's file content from its named template."""
+    tname = harness.get("template")
+    if not tname or tname not in templates:
+        raise SystemExit("ERROR: harness '%s' references unknown template '%s'" % (harness.get("id"), tname))
+    return subst(templates[tname],
+                 {"generated_banner": banner, "body": body_text},
+                 harness.get("template_extra"))
+
+def generated_active():
+    return [h for h in harnesses if h.get("generated") and h.get("status") == "active"]
+
+def write(path, content):
+    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+    open(path, "w").write(content)
+
+# ── Mode: list ───────────────────────────────────────────────────────────────
+if mode == "list":
+    print("%-18s %-22s %-15s %-9s %-7s %s" % ("id", "tool", "tier", "status", "gen", "path"))
+    print("-" * 100)
+    for h in harnesses:
+        print("%-18s %-22s %-15s %-9s %-7s %s" % (
+            h.get("id", "?"), (h.get("tool") or "")[:22], h.get("tier", "?"),
+            h.get("status", "?"), str(bool(h.get("generated"))).lower(), h.get("path") or "(none)"))
+    print("\nGenerated on `render`: " + ", ".join(h["id"] for h in generated_active()))
+    sys.exit(0)
+
+# ── Mode: render / check (root install paths) ────────────────────────────────
+if mode in ("render", "check"):
+    drift, wrote = [], []
+    for h in generated_active():
+        path = os.path.join(repo, h["path"])
+        content = render_file(h, body)
+        if mode == "check":
+            existing = open(path).read() if os.path.exists(path) else None
+            if existing != content:
+                drift.append(h["path"])
+        else:
+            write(path, content)
+            wrote.append(h["path"])
+    if mode == "check":
+        if drift:
+            print("DRIFT — these generated files are out of sync with agent/session-protocol.md:")
+            for d in drift:
+                print("  - " + d)
+            print("\nRun: ./scripts/render-harness.sh")
+            sys.exit(1)
+        print("OK — all %d generated harness files are in sync." % len(generated_active()))
+        sys.exit(0)
+    for w in wrote:
+        print("rendered: " + w)
+    print("\n%d files rendered from agent/session-protocol.md." % len(wrote))
+    print("Note: CLAUDE.md is import-tier (hand-maintained) — not regenerated.")
+    sys.exit(0)
+
+# ── Mode: project (per-project entrypoints under projects/<PID>/) ────────────
+if mode == "project":
+    proj_dir = os.path.join(repo, "projects", pid)
+    if not os.path.isdir(proj_dir):
+        raise SystemExit("ERROR: project dir not found: projects/%s (seed it first)" % pid)
+    # Compose a per-project body = canonical protocol + the project's own agent.md
+    # inlined (so non-import tools get full project context in one file).
+    pp_agent = os.path.join(proj_dir, "agent.md")
+    if os.path.exists(pp_agent):
+        proj_ctx = open(pp_agent).read().rstrip("\n")
+    else:
+        proj_ctx = "See `projects/%s/agent.md` for project-specific context." % pid
+    pp_body = body + "\n\n---\n\n# Project entrypoint — " + pid + "\n\n" + proj_ctx
+    wrote = []
+    for h in harnesses:
+        if h.get("status") != "active":
+            continue
+        # Claude: write the @import stub (expands canonical + project agent.md at launch).
+        if h.get("tier") == "import" and h.get("per_project_path"):
+            ppath = os.path.join(repo, h["per_project_path"].replace("{project_id}", pid))
+            stub = (h.get("per_project_template") or "").rstrip("\n") + "\n"
+            write(ppath, stub)
+            wrote.append(os.path.relpath(ppath, repo))
+            continue
+        # Generated tools: render their template into projects/<PID>/<path> with the composed body.
+        if h.get("generated") and h.get("path"):
+            ppath = os.path.join(proj_dir, h["path"])
+            write(ppath, render_file(h, pp_body))
+            wrote.append(os.path.relpath(ppath, repo))
+    for w in wrote:
+        print("rendered: " + w)
+    print("\n%d per-project entrypoints written under projects/%s/." % (len(wrote), pid))
+    sys.exit(0)
+PY

package/scripts/resume.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Script: resume
+# Purpose: Transitions a project from PAUSED to ACTIVE with mandatory base sync.
+# Usage:   bash resume.sh <project_id>
+# Compliance: C01 for knowledge sync (POL-122); C02 for state transition (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 "=== resume: $PROJECT_ID"
+echo ""
+
+PROJECT_YAML=$(get_project_yaml "$PROJECT_ID")
+check_project_exists "$PROJECT_ID"
+
+# ── Pre-conditions ────────────────────────────────────────────────────────────
+
+require_project_status "$PROJECT_YAML" "paused"
+
+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 resume — you need write access to the project's GitHub Project ($GH_PROJECT)."
+
+BRANCH=$(project_branch_for_id "$PROJECT_ID")
+
+# ── C01: Mandatory DEFAULT_BRANCH sync for workspace repo ────────────────────
+
+echo "[ C01 ] Syncing workspace repo: $DEFAULT_BRANCH → $BRANCH..."
+cd "$REPO_ROOT"
+git fetch origin "$DEFAULT_BRANCH"
+git fetch origin "$BRANCH"
+git checkout "$BRANCH"
+
+# Merge DEFAULT_BRANCH into project branch — exit 2 on conflict (caller resolves)
+if ! git merge --no-edit "origin/$DEFAULT_BRANCH" 2>/dev/null; then
+  echo ""
+  echo "MERGE CONFLICT: $DEFAULT_BRANCH → $BRANCH in workspace repo."
+  echo "Resolve conflicts manually, commit, then re-run: bash resume.sh $PROJECT_ID"
+  exit 2
+fi
+git push origin "$BRANCH"
+info "Workspace repo synced."
+
+# ── C01: Mandatory base_branch sync for each code repo ───────────────────────
+
+while IFS= read -r repo_url; do
+  REPO_NAME=$(get_repo_name "$repo_url")
+  REPO_DIR="$(repo_clone_dir "$PROJECT_ID" "$REPO_NAME")"
+  REPO_BASE=$(get_repo_base_branch "$PROJECT_YAML" "$repo_url")
+
+  if [[ ! -e "$REPO_DIR/.git" ]]; then
+    warn "Repo $REPO_NAME not cloned locally — skipping sync."
+    continue
+  fi
+
+  echo "[ C01 ] Syncing $REPO_NAME: $REPO_BASE → $BRANCH..."
+  git -C "$REPO_DIR" fetch origin "$REPO_BASE"
+  git -C "$REPO_DIR" checkout "$BRANCH"
+  if ! git -C "$REPO_DIR" merge --no-edit "origin/$REPO_BASE" 2>/dev/null; then
+    echo ""
+    echo "MERGE CONFLICT: $REPO_BASE → $BRANCH in $REPO_NAME."
+    echo "Resolve conflicts manually, commit, then re-run: bash resume.sh $PROJECT_ID"
+    exit 2
+  fi
+  git -C "$REPO_DIR" push origin "$BRANCH"
+  info "$REPO_NAME synced."
+done < <(get_project_repos "$PROJECT_YAML")
+
+# ── Update project.yaml ───────────────────────────────────────────────────────
+
+yaml_set "$PROJECT_YAML" "paused_at" "~"
+yaml_set "$PROJECT_YAML" "status"    "active"
+
+TODAY=$(today)
+
+cd "$REPO_ROOT"
+git checkout "$BRANCH"
+git add "projects/$PROJECT_ID/project.yaml"
+git commit -m "resume: $PROJECT_ID (synced with $DEFAULT_BRANCH)"
+git push origin "$BRANCH"
+
+# ── Reflect resume in the registry index on the default branch + README mirror ─
+registry_set_status_on_main "$PROJECT_ID" "active"
+project_readme_mirror "$PROJECT_ID" "$(yaml_get "$PROJECT_YAML" github_project)" "active" \
+  "$ASSIGNED_TO" "$(yaml_get "$PROJECT_YAML" seeded_by)" "$BRANCH" || true
+
+echo ""
+echo "=== Project resumed."
+echo "    Status: active"
+echo "    All branches synced with their base branches."
+echo ""
+echo "[ C01 ] Reload all four knowledge layers fresh before starting work:"
+echo "    1. $WORKSPACE_REPO/knowledge/"
+echo "    2. $WORKSPACE_REPO/projects/$PROJECT_ID/knowledge/"
+echo "    3. <repo>/knowledge/ for each repo"
+echo "    4. \$PRJ_GOV_LOC/preferences/<your-gh-login>.md  (your own only)"