@svayam-opensource/prj 0.5.1

package/scripts/sync-from-publish.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# Script: sync-from-publish
+# Purpose: Pull universal framework updates from `publish` into `main`,
+#          preserving main's private overlay (org-config.yaml, registry.yaml,
+#          projects/). Direction A: framework files contain no placeholders,
+#          so this is a plain merge — no re-substitution step.
+#
+# Usage:   bash scripts/sync-from-publish.sh [--dry-run] [--no-push]
+#
+# Flags:
+#   --dry-run   Show what would be merged without making any changes.
+#   --no-push   Do the merge + validation locally; do not push to origin/main.
+#
+# Privacy: NEVER syncs main → publish. One-way (publish → main).
+#
+# Strategy:
+#   1. Verify on main, clean, fast-forwardable from origin.
+#   2. Show commits to be merged; confirm (skip if --dry-run).
+#   3. Create ephemeral test branch test-sync-from-publish from main.
+#   4. Merge publish with -X theirs (auto-prefer publish for content conflicts).
+#   5. Restore main's private overlay (org-config.yaml, registry.yaml, projects/)
+#      from main's pre-merge state.
+#   6. Run validators — fail if any placeholders leaked (framework files must
+#      stay placeholder-free; validator's placeholder check is always-on).
+#   7. On pass: fast-forward main to test branch tip, push, delete test branch.
+#   8. On fail: discard test branch, restore main, exit non-zero.
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+DRY_RUN=false
+NO_PUSH=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+    --no-push) NO_PUSH=true ;;
+    --allow-downgrade) export ALLOW_DOWNGRADE=true ;;
+    -h|--help)
+      grep '^# ' "$0" | sed 's/^# //;s/^#//'
+      exit 0
+      ;;
+    *) hard_stop "Unknown flag: $arg (see --help)" ;;
+  esac
+done
+
+cd "$REPO_ROOT"
+
+# ── Pre-conditions ────────────────────────────────────────────────────────────
+
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+[[ "$CURRENT_BRANCH" == "$DEFAULT_BRANCH" ]] \
+  || hard_stop "Run from '$DEFAULT_BRANCH' (currently on '$CURRENT_BRANCH')."
+
+[[ -z "$(git status --porcelain)" ]] \
+  || hard_stop "Uncommitted changes present. Stash or commit first."
+
+# ── Fetch latest ──────────────────────────────────────────────────────────────
+
+echo "=== sync-from-publish"
+$DRY_RUN && echo "    (dry-run mode — no changes will be made)"
+$NO_PUSH && echo "    (--no-push — will merge locally but not push)"
+echo ""
+
+info "Fetching latest..."
+git fetch origin "$DEFAULT_BRANCH"
+git fetch origin publish
+
+if ! git pull --ff-only origin "$DEFAULT_BRANCH"; then
+  hard_stop "Cannot fast-forward local '$DEFAULT_BRANCH' from origin."
+fi
+
+# ── Identify commits to sync ──────────────────────────────────────────────────
+
+COMMITS_TO_SYNC=$(git rev-list --count "$DEFAULT_BRANCH..origin/publish" 2>/dev/null || echo 0)
+
+if [[ "$COMMITS_TO_SYNC" -eq 0 ]]; then
+  echo "✓ '$DEFAULT_BRANCH' is already up to date with publish."
+  exit 0
+fi
+
+# ── Framework version guard: never let an OLDER publish overwrite main ────────
+PUB_VER="$(git show origin/publish:framework/VERSION 2>/dev/null | tr -d '[:space:]')"
+CUR_VER="$(git show "$DEFAULT_BRANCH:framework/VERSION" 2>/dev/null | tr -d '[:space:]')"
+[[ -n "$PUB_VER" ]] && info "framework: publish v$PUB_VER → $DEFAULT_BRANCH v$CUR_VER"
+assert_no_framework_downgrade "$PUB_VER" "$CUR_VER" "sync-from-publish"
+
+echo ""
+echo "Commits on publish not yet on $DEFAULT_BRANCH ($COMMITS_TO_SYNC total):"
+git log --oneline "$DEFAULT_BRANCH..origin/publish" | head -30
+echo ""
+
+if $DRY_RUN; then
+  echo ""
+  info "Dry-run: would merge the above commits into $DEFAULT_BRANCH using -X theirs,"
+  info "         restore private overlay (org-config.yaml, registry.yaml, projects/),"
+  info "         run validators,"
+  info "         and (unless --no-push) push to origin/$DEFAULT_BRANCH."
+  exit 0
+fi
+
+confirm "Proceed with merge?"
+
+# ── Test branch + merge ───────────────────────────────────────────────────────
+
+TEST_BRANCH="test-sync-from-publish"
+ORIGINAL_SHA=$(git rev-parse HEAD)
+
+cleanup_on_fail() {
+  echo ""
+  warn "Sync failed — restoring '$DEFAULT_BRANCH' to pre-sync state."
+  git merge --abort 2>/dev/null || true
+  git checkout "$DEFAULT_BRANCH" 2>/dev/null || true
+  git reset --hard "$ORIGINAL_SHA" 2>/dev/null || true
+  git branch -D "$TEST_BRANCH" 2>/dev/null || true
+}
+
+if git rev-parse --verify "$TEST_BRANCH" &>/dev/null; then
+  warn "Stale test branch '$TEST_BRANCH' exists — deleting."
+  git branch -D "$TEST_BRANCH"
+fi
+git checkout -b "$TEST_BRANCH"
+
+info "Merging publish with -X theirs (auto-prefers publish for conflicts)..."
+if ! git merge -X theirs --no-edit -m "sync: publish → $DEFAULT_BRANCH" origin/publish; then
+  cleanup_on_fail
+  hard_stop "Merge failed despite -X theirs. Manual intervention required."
+fi
+
+# ── Restore private overlay from pre-merge main ───────────────────────────────
+
+info "Restoring private overlay (org-config.yaml, registry.yaml, projects/)..."
+
+# HEAD^1 is the first parent (pre-merge main); HEAD^2 is publish's tip.
+# We want main's pre-merge content for these specific paths.
+PRIVATE_PATHS=("org-config.yaml" "registry.yaml")
+for path in "${PRIVATE_PATHS[@]}"; do
+  if git ls-tree HEAD^1 -- "$path" &>/dev/null; then
+    git checkout HEAD^1 -- "$path"
+  fi
+done
+
+# projects/ may exist on main only (publish has empty projects/)
+if git ls-tree HEAD^1 -- projects/ &>/dev/null; then
+  # Remove any projects content that came from publish, then restore main's
+  git rm -rf --cached projects/ &>/dev/null || true
+  rm -rf projects
+  git checkout HEAD^1 -- projects/
+fi
+
+# Amend the merge commit with the overlay restorations.
+if [[ -n "$(git diff --cached --name-only)" ]]; then
+  git commit --amend --no-edit
+fi
+
+# ── Validate the merged tree ──────────────────────────────────────────────────
+
+VALIDATOR="$REPO_ROOT/scripts/validate/run.py"
+if [[ -x "$VALIDATOR" ]]; then
+  echo ""
+  info "Running validators against merged tree..."
+  echo ""
+  if ! python3 "$VALIDATOR" "$REPO_ROOT"; then
+    echo ""
+    cleanup_on_fail
+    hard_stop "Validation FAILED — sync rolled back. '$DEFAULT_BRANCH' is unchanged."
+  fi
+else
+  warn "Validator not found at $VALIDATOR — skipping post-merge validation."
+fi
+
+# ── Promote test branch to main and clean up ──────────────────────────────────
+
+echo ""
+info "Validation passed. Promoting to '$DEFAULT_BRANCH'..."
+git checkout "$DEFAULT_BRANCH"
+git merge --ff-only "$TEST_BRANCH"
+git branch -d "$TEST_BRANCH"
+
+# ── Push (unless --no-push) ───────────────────────────────────────────────────
+
+if $NO_PUSH; then
+  echo ""
+  info "✓ Sync complete locally. NOT pushed (--no-push)."
+  info "  When ready: git push origin $DEFAULT_BRANCH"
+else
+  echo ""
+  info "Pushing to origin/$DEFAULT_BRANCH..."
+  git push origin "$DEFAULT_BRANCH"
+  echo ""
+  info "✓ Sync complete. '$DEFAULT_BRANCH' updated and pushed."
+fi

package/scripts/sync.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Script: sync
+# Purpose: Merges latest DEFAULT_BRANCH/base into active project branch on demand.
+#          Use mid-project to stay current without pausing/resuming.
+# Usage:   bash sync.sh <project_id>
+# Compliance: C03 — encouraged but not mandatory (POL-122)
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+# ── Inputs ────────────────────────────────────────────────────────────────────
+
+PROJECT_ID="${1:-}"
+[[ -n "$PROJECT_ID" ]] || hard_stop "Usage: $0 <project_id>"
+
+echo "=== sync: $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 sync — '$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."
+echo ""
+
+# ── Sync workspace repo ───────────────────────────────────────────────────────
+
+echo "Syncing workspace repo: $DEFAULT_BRANCH → $BRANCH..."
+cd "$REPO_ROOT"
+git fetch origin "$DEFAULT_BRANCH"
+git checkout "$BRANCH"
+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 sync.sh $PROJECT_ID"
+  exit 2
+fi
+git push origin "$BRANCH"
+info "Workspace repo synced."
+
+# ── Sync 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 "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 sync.sh $PROJECT_ID"
+    exit 2
+  fi
+  git -C "$REPO_DIR" push origin "$BRANCH"
+  info "$REPO_NAME synced."
+done < <(get_project_repos "$PROJECT_YAML")
+
+echo ""
+echo "=== Sync complete. All project branches are current."
+echo ""
+echo "[ C03 ] Reload knowledge layers before continuing work:"
+echo "    1. $WORKSPACE_REPO/knowledge/"
+echo "    2. $WORKSPACE_REPO/projects/$PROJECT_ID/knowledge/"
+echo "    3. <repo>/knowledge/ for each repo"

package/scripts/test-merge.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# Script: test-merge
+# Purpose: Pre-merge gate for the workspace repo's default branch.
+#          Validates that merging <source-branch> will not violate schema
+#          or invariants. On pass, fast-forwards local default to the
+#          merged tip — caller pushes. On fail, leaves local default
+#          unchanged.
+#
+# Usage:   bash scripts/test-merge.sh <source-branch>
+#
+# Behavior:
+#   1. Sync local $DEFAULT_BRANCH with remote (only legitimate remote read)
+#   2. Create ephemeral test branch test-merge/<source> from $DEFAULT_BRANCH
+#   3. Merge <source> into test branch (no push)
+#   4. Run scripts/validate/run.py against the merged tree
+#   5a. Pass: fast-forward $DEFAULT_BRANCH to test-merge tip; delete test branch
+#   5b. Fail: discard test branch; $DEFAULT_BRANCH untouched; exit non-zero
+#
+# This script is the foundation of the test-merge gate strategy. See:
+#   knowledge/guidance/test-merge-gate.md (TODO)
+#
+# Compliance: C01 — workspace integrity gate
+
+set -euo pipefail
+source "$(dirname "$0")/lib.sh"
+load_config
+
+SOURCE_BRANCH="${1:-}"
+[[ -n "$SOURCE_BRANCH" ]] || hard_stop "Usage: $0 <source-branch>"
+
+cd "$REPO_ROOT"
+
+ORIGINAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+TEST_BRANCH="test-merge/$SOURCE_BRANCH"
+VALIDATOR="$REPO_ROOT/scripts/validate/run.py"
+
+[[ -x "$VALIDATOR" ]] || hard_stop "Validator not found or not executable: $VALIDATOR"
+
+# Verify source branch exists locally or on remote
+if ! git rev-parse --verify "$SOURCE_BRANCH" &>/dev/null; then
+  if git ls-remote --exit-code origin "$SOURCE_BRANCH" &>/dev/null; then
+    info "Fetching $SOURCE_BRANCH from origin..."
+    git fetch origin "$SOURCE_BRANCH:$SOURCE_BRANCH" 2>/dev/null \
+      || git fetch origin "$SOURCE_BRANCH"
+  else
+    hard_stop "Source branch '$SOURCE_BRANCH' not found locally or on remote."
+  fi
+fi
+
+# Cleanup helper — used on failure to restore state
+on_fail() {
+  git merge --abort 2>/dev/null || true
+  git checkout "$ORIGINAL_BRANCH" 2>/dev/null \
+    || git checkout "$DEFAULT_BRANCH" 2>/dev/null || true
+  git branch -D "$TEST_BRANCH" 2>/dev/null || true
+}
+
+# 1. Sync local default with remote
+info "Syncing local $DEFAULT_BRANCH with origin..."
+git fetch origin "$DEFAULT_BRANCH"
+git checkout "$DEFAULT_BRANCH"
+if ! git pull --ff-only origin "$DEFAULT_BRANCH"; then
+  on_fail
+  hard_stop "Cannot fast-forward local $DEFAULT_BRANCH from remote — resolve manually."
+fi
+
+# 2. Create ephemeral test branch from current default tip
+if git rev-parse --verify "$TEST_BRANCH" &>/dev/null; then
+  warn "Stale test branch '$TEST_BRANCH' exists from a previous run — deleting."
+  git branch -D "$TEST_BRANCH"
+fi
+git checkout -b "$TEST_BRANCH"
+
+# 3. Merge source into test branch (local only)
+info "Test-merging '$SOURCE_BRANCH' into '$TEST_BRANCH'..."
+if ! git merge --no-ff -m "test-merge: $SOURCE_BRANCH" "$SOURCE_BRANCH"; then
+  on_fail
+  hard_stop "Merge conflict: '$SOURCE_BRANCH' cannot merge cleanly into '$DEFAULT_BRANCH'. Resolve before retrying."
+fi
+
+# 4. Run validators against merged tree
+echo ""
+info "Running validators against merged tree..."
+echo ""
+if ! python3 "$VALIDATOR" "$REPO_ROOT"; then
+  echo ""
+  on_fail
+  hard_stop "Test-merge gate FAILED for '$SOURCE_BRANCH'. Local '$DEFAULT_BRANCH' is unchanged."
+fi
+
+# 5. Pass: fast-forward default to test-merge tip; clean up test branch
+echo ""
+info "Test-merge gate PASSED. Promoting to local '$DEFAULT_BRANCH'..."
+git checkout "$DEFAULT_BRANCH"
+git merge --ff-only "$TEST_BRANCH"
+git branch -d "$TEST_BRANCH"
+
+echo ""
+info "✓ Local '$DEFAULT_BRANCH' now contains the merge of '$SOURCE_BRANCH'."
+info "  Caller should: git push origin $DEFAULT_BRANCH"

package/scripts/validate/check_knowledge.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+Knowledge Organization Standard enforcement (POL-416).
+
+Checks every *.md under knowledge/ (org tree only — framework/ is the
+upstream template and excluded):
+
+  1. front-matter — present, schema-valid, domain/layer agree with the
+     file's folder (domain-root instruments are exempt from layer-folder
+     agreement; their paths are pinned by policy text — see the C03
+     deviation in the PRJ-005 migration).
+  2. orphan check — every non-README doc is linked from at least one other
+     knowledge doc (its layer index or a journey doc).
+  3. journey purity — paths/*.md are links-in-order docs: no code blocks,
+     no embedded images, and a minimum link density.
+  4. link check — every relative md link resolves; no [[wikilinks]].
+  5. diagram rule — no binary diagram embeds (png/jpg/gif) in knowledge/;
+     diagrams are Mermaid text (POL-414). Files whose link path contains
+     "screenshot" are exempt.
+
+Superseded redirect stubs (status: superseded) are exempt from orphan and
+folder-agreement checks but must still parse.
+"""
+
+import re
+from pathlib import Path
+
+DOMAINS = {
+    "policies", "legal", "architecture/system", "architecture/data",
+    "development", "testing", "deployment", "infrastructure", "support",
+    "compliance", "navigation",
+}
+LAYERS = {"mandate", "procedure", "pattern", "use-case", "spec", "compliance", "path"}
+COMPLIANCE = {"C01", "C02", "C03", "instructional", "descriptive", "evidence"}
+STATUSES = {"current", "draft", "superseded"}
+LAYER_FOLDER = {
+    "mandates": "mandate", "procedures": "procedure", "patterns": "pattern",
+    "use-cases": "use-case", "specs": "spec", "compliance": "compliance",
+    "paths": "path",
+}
+FM_RE = re.compile(r"\A---\n(.*?)\n---\n", re.S)
+LINK_RE = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)")
+WIKILINK_RE = re.compile(r"\[\[[^\]]+\]\]")
+IMG_RE = re.compile(r"!\[[^\]]*\]\(([^)\s]+)\)")
+
+
+def _front_matter(text: str) -> dict | None:
+    m = FM_RE.match(text)
+    if not m:
+        return None
+    fm = {}
+    for line in m.group(1).splitlines():
+        if ":" in line and not line.lstrip().startswith("#"):
+            k, _, v = line.partition(":")
+            fm[k.strip()] = v.strip()
+    return fm
+
+
+def check_knowledge(repo_root: Path) -> list[str]:
+    errors: list[str] = []
+    kroot = repo_root / "knowledge"
+    if not kroot.is_dir():
+        return ["knowledge/ directory missing"]
+
+    docs: dict[Path, str] = {
+        p: p.read_text(encoding="utf-8", errors="replace")
+        for p in sorted(kroot.rglob("*.md"))
+    }
+    linked: set[Path] = set()
+
+    def _strip_code(t: str) -> str:
+        # CommonMark-ish fence matching: a fence opened with N backticks only
+        # closes on a line with >= N backticks (so ````markdown wrappers can
+        # embed ``` blocks). Then inline spans; then indented code (4+ spaces).
+        out: list[str] = []
+        fence_len = 0  # 0 = not in a fence
+        for l in t.splitlines():
+            stripped = l.lstrip()
+            m = re.match(r"^(`{3,})", stripped)
+            if m:
+                n = len(m.group(1))
+                if fence_len == 0:
+                    fence_len = n          # open
+                elif n >= fence_len:
+                    fence_len = 0          # close
+                continue
+            if fence_len == 0:
+                out.append(l)
+        t = re.sub(r"`[^`\n]*`", "", "\n".join(out))
+        return "\n".join(l for l in t.splitlines() if not l.startswith("    "))
+
+    # Pass 1 — links, wikilinks, images, and link-graph construction
+    for p, text in docs.items():
+        rel = p.relative_to(repo_root)
+        if WIKILINK_RE.search(_strip_code(text)):
+            errors.append(f"{rel}: [[wikilink]] found — use relative markdown links (POL-413)")
+        for target in IMG_RE.findall(text):
+            if target.lower().endswith((".png", ".jpg", ".jpeg", ".gif")) and "screenshot" not in target.lower():
+                errors.append(f"{rel}: binary diagram embed '{target}' — diagrams are Mermaid text (POL-414)")
+        for target in LINK_RE.findall(text):
+            if target.startswith(("http://", "https://", "mailto:", "#")):
+                continue
+            tpath = (p.parent / target.split("#")[0]).resolve()
+            if not tpath.exists():
+                errors.append(f"{rel}: broken link '{target}'")
+            else:
+                try:
+                    linked.add(tpath.relative_to(repo_root.resolve()))
+                except ValueError:
+                    pass
+
+    # Pass 2 — front-matter, folder agreement, orphan, journey purity
+    for p, text in docs.items():
+        rel = p.relative_to(repo_root)
+        fm = _front_matter(text)
+        if fm is None:
+            errors.append(f"{rel}: missing front-matter (POL-408)")
+            continue
+        for key, allowed in (("domain", DOMAINS), ("layer", LAYERS),
+                             ("compliance", COMPLIANCE), ("status", STATUSES)):
+            val = fm.get(key)
+            if val not in allowed:
+                errors.append(f"{rel}: front-matter {key}='{val}' invalid (POL-408)")
+        if not fm.get("owner"):
+            errors.append(f"{rel}: front-matter owner missing (POL-408)")
+
+        if fm.get("status") == "superseded":
+            continue  # redirect stubs: parse-only
+
+        parts = rel.parts  # ('knowledge', <domain..>, [layer], file)
+        folder_layer = None
+        for seg in parts[1:-1]:
+            if seg in LAYER_FOLDER:
+                folder_layer = LAYER_FOLDER[seg]
+        if folder_layer and fm.get("layer") != folder_layer:
+            errors.append(
+                f"{rel}: layer '{fm.get('layer')}' disagrees with folder '{folder_layer}' (POL-408)"
+            )
+
+        # Orphan check: non-README docs must be linked from somewhere.
+        if p.name != "README.md":
+            try:
+                relresolved = p.resolve().relative_to(repo_root.resolve())
+            except ValueError:
+                relresolved = rel
+            if relresolved not in linked:
+                errors.append(f"{rel}: orphan — not linked from any index or journey (POL-416)")
+
+        # Journey purity
+        if parts[1] == "paths" and p.name != "README.md":
+            if "```" in text:
+                errors.append(f"{rel}: journey docs are links-only — code block found (POL-410)")
+            if IMG_RE.search(text):
+                errors.append(f"{rel}: journey docs are links-only — image found (POL-410)")
+            if len(LINK_RE.findall(text)) < 3:
+                errors.append(f"{rel}: journey doc has fewer than 3 links — is it a journey? (POL-410)")
+
+    return errors