From 177fb618b994572b4f58424efaab851bb4293cf9 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Fri, 1 May 2026 06:35:32 +0300 Subject: [PATCH 01/33] docs(spec): add git status tracking design Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../2026-05-01-git-status-tracking-design.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-01-git-status-tracking-design.md diff --git a/docs/superpowers/specs/2026-05-01-git-status-tracking-design.md b/docs/superpowers/specs/2026-05-01-git-status-tracking-design.md new file mode 100644 index 0000000..480df38 --- /dev/null +++ b/docs/superpowers/specs/2026-05-01-git-status-tracking-design.md @@ -0,0 +1,78 @@ +# Git Status Tracking Design (ROS Parent Repo) + +## Problem +We need persistent tracking of repository file-state changes in the ROS parent repo, with automatic capture whenever `git status` is run, and with append-only history plus a latest snapshot. + +## Scope +- In scope: ROS parent repo only (`/mnt/data/ros` top-level). +- In scope: track untracked, modified, deleted, and renamed paths. +- Out of scope: tracking inside `program/*` submodules. + +## Approach +Implement a shell-level `git` shim (Bash function) that intercepts `git status` and `git st`: +1. Detect current git top-level. +2. If top-level equals ROS parent repo, run tracker collector. +3. Collector writes tracking artifacts. +4. Always forward command to the real git binary. +5. For non-status git commands, pass through unchanged. + +## Tracking Artifacts +Store under repo-local `.tracking/`: + +- `latest.json`: latest full structured snapshot. +- `history.ndjson`: append-only event history (one JSON object per line). +- `latest.txt`: readable summary for quick inspection. + +Each tracking event includes: +- `timestamp` (ISO-8601) +- `repo_root` +- `branch` +- `untracked[]` +- `modified[]` +- `deleted[]` +- `renamed[]` + +## Data Flow +1. User runs `git status` (or `git st`). +2. Bash shim checks repo root. +3. If ROS parent repo, capture `git status --porcelain=v1` and parse by status code. +4. Generate snapshot object and write: + - overwrite `latest.json` + - append to `history.ndjson` + - overwrite `latest.txt` +5. Execute original `git status` output for user. + +## Error Handling +- Tracker failures must not block git usage. +- On parser or write failure, print a warning to stderr and continue to real git command. +- If `.tracking/` is missing, create it automatically. +- If `history.ndjson` exceeds size threshold, rotate to `history..ndjson` and continue with new file. + +## Safety Constraints +- Run collector only when top-level repo path exactly matches `/mnt/data/ros`. +- Never recurse into submodules for collection. +- Never modify tracked source files; only write under `.tracking/`. + +## Implementation Units +1. **Collector script** (`scripts/track-git-status.sh`) + - Read porcelain output + - Parse and build JSON payload + - Write artifacts and rotate history +2. **Shell shim snippet** (`session/docs/snippets/git-tracking-shim.bash`) + - Function override for `git` + - Conditional call to collector for `status`/`st` +3. **Installer helper** (`scripts/install-git-tracking-shim.sh`) + - Idempotently append shim source block to `~/.bashrc` + +## Validation Plan +- Run `git status` with known untracked/modified/deleted/renamed examples. +- Confirm `.tracking/latest.json`, `.tracking/history.ndjson`, `.tracking/latest.txt` are produced. +- Confirm multiple `git status` calls append events. +- Confirm non-status git commands are unaffected. +- Confirm tracker does not run in submodules. + +## Success Criteria +- Every `git status` in ROS parent repo produces/updates tracking artifacts. +- History is append-only and survives shell sessions. +- Tracker is transparent to normal git workflow. +- Submodule repositories are not tracked by this mechanism. From cd39c7be820825bfb8458ee60ad13bf0b13b8eb8 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sat, 2 May 2026 20:09:05 +0300 Subject: [PATCH 02/33] docs(plan): add git status tracking implementation plan Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ...5-02-git-status-tracking-implementation.md | 406 ++++++++++++++++++ 1 file changed, 406 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md diff --git a/docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md b/docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md new file mode 100644 index 0000000..efd69d5 --- /dev/null +++ b/docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md @@ -0,0 +1,406 @@ +# Git Status Tracking Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add automatic ROS-parent-only tracking for `git status` that writes append-only history and latest snapshots without blocking normal git usage. + +**Architecture:** Implement a small Bash collector script that parses `git status --porcelain=v1` and writes `.tracking/latest.json`, `.tracking/history.ndjson`, and `.tracking/latest.txt`. Add a Bash `git` shim snippet that runs the collector only for `status`/`st` at `/mnt/data/ros`, plus an idempotent installer that sources the shim from `~/.bashrc`. Keep submodules excluded by strict top-level path check. + +**Tech Stack:** Bash, git porcelain output, jq (JSON construction), GNU coreutils. + +--- + +## File Structure Plan + +- Create: `scripts/track-git-status.sh` — collector and writer for tracking artifacts. +- Create: `scripts/install-git-tracking-shim.sh` — idempotent installer into `~/.bashrc`. +- Create: `session/docs/snippets/git-tracking-shim.bash` — shell function shim for `git`. +- Create: `scripts/tests/test-track-git-status.sh` — collector behavior test script. +- Create: `scripts/tests/test-git-tracking-shim.sh` — shim routing test script. +- Modify: `.gitignore` — ignore `.tracking/`. + +--- + +### Task 1: Build collector with TDD for snapshot generation + +**Files:** +- Create: `scripts/tests/test-track-git-status.sh` +- Create: `scripts/track-git-status.sh` +- Modify: `.gitignore` + +- [ ] **Step 1: Write failing test for snapshot/history creation** + +```bash +#!/usr/bin/env bash +set -euo pipefail + +ROOT="/mnt/data/ros" +TMP="$(mktemp -d)" +trap 'rm -rf "$TMP"' EXIT + +cat > "$TMP/porcelain.txt" <<'EOF' +?? new.txt + M changed.md + D removed.log +R old.py -> new.py +EOF + +SCRIPT="$ROOT/scripts/track-git-status.sh" +if [ -x "$SCRIPT" ]; then + "$SCRIPT" \ + --repo-root "$ROOT" \ + --branch "main" \ + --porcelain-file "$TMP/porcelain.txt" \ + --tracking-dir "$TMP/.tracking" +fi + +test -f "$TMP/.tracking/latest.json" +test -f "$TMP/.tracking/history.ndjson" +test -f "$TMP/.tracking/latest.txt" +grep -q '"untracked":\["new.txt"\]' "$TMP/.tracking/latest.json" +grep -q '"modified":\["changed.md"\]' "$TMP/.tracking/latest.json" +grep -q '"deleted":\["removed.log"\]' "$TMP/.tracking/latest.json" +grep -q '"renamed":\["old.py -> new.py"\]' "$TMP/.tracking/latest.json" +``` + +- [ ] **Step 2: Run test to verify failure** + +Run: `bash scripts/tests/test-track-git-status.sh` +Expected: FAIL because `scripts/track-git-status.sh` does not exist yet. + +- [ ] **Step 3: Write minimal collector implementation** + +```bash +#!/usr/bin/env bash +set -euo pipefail + +REPO_ROOT="" +BRANCH="" +PORCELAIN_FILE="" +TRACKING_DIR="" +MAX_BYTES="${TRACKING_MAX_BYTES:-10485760}" + +while [[ $# -gt 0 ]]; do + case "$1" in + --repo-root) REPO_ROOT="$2"; shift 2 ;; + --branch) BRANCH="$2"; shift 2 ;; + --porcelain-file) PORCELAIN_FILE="$2"; shift 2 ;; + --tracking-dir) TRACKING_DIR="$2"; shift 2 ;; + *) echo "Unknown arg: $1" >&2; exit 2 ;; + esac +done + +mkdir -p "$TRACKING_DIR" +HISTORY="$TRACKING_DIR/history.ndjson" +LATEST_JSON="$TRACKING_DIR/latest.json" +LATEST_TXT="$TRACKING_DIR/latest.txt" + +if [[ -f "$HISTORY" ]]; then + size="$(wc -c < "$HISTORY" | tr -d ' ')" + if [[ "$size" -gt "$MAX_BYTES" ]]; then + mv "$HISTORY" "$TRACKING_DIR/history.$(date -u +%Y%m%dT%H%M%SZ).ndjson" + fi +fi + +mapfile -t UNTRACKED < <(awk '/^\?\? /{sub(/^\?\? /,""); print}' "$PORCELAIN_FILE") +mapfile -t MODIFIED < <(awk '/^( M|M |MM)/{sub(/^../,""); sub(/^ /,""); print}' "$PORCELAIN_FILE") +mapfile -t DELETED < <(awk '/^( D|D )/{sub(/^../,""); sub(/^ /,""); print}' "$PORCELAIN_FILE") +mapfile -t RENAMED < <(awk '/^R/{sub(/^../,""); sub(/^ /,""); print}' "$PORCELAIN_FILE") + +json="$(jq -cn \ + --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ + --arg repo "$REPO_ROOT" \ + --arg branch "$BRANCH" \ + --argjson untracked "$(printf '%s\n' "${UNTRACKED[@]:-}" | jq -Rsc 'split("\n")[:-1]')" \ + --argjson modified "$(printf '%s\n' "${MODIFIED[@]:-}" | jq -Rsc 'split("\n")[:-1]')" \ + --argjson deleted "$(printf '%s\n' "${DELETED[@]:-}" | jq -Rsc 'split("\n")[:-1]')" \ + --argjson renamed "$(printf '%s\n' "${RENAMED[@]:-}" | jq -Rsc 'split("\n")[:-1]')" \ + '{timestamp:$ts,repo_root:$repo,branch:$branch,untracked:$untracked,modified:$modified,deleted:$deleted,renamed:$renamed}')" + +printf '%s\n' "$json" > "$LATEST_JSON" +printf '%s\n' "$json" >> "$HISTORY" +{ + echo "timestamp: $(jq -r '.timestamp' "$LATEST_JSON")" + echo "repo: $(jq -r '.repo_root' "$LATEST_JSON")" + echo "branch: $(jq -r '.branch' "$LATEST_JSON")" + echo "untracked: $(jq -r '.untracked | length' "$LATEST_JSON")" + echo "modified: $(jq -r '.modified | length' "$LATEST_JSON")" + echo "deleted: $(jq -r '.deleted | length' "$LATEST_JSON")" + echo "renamed: $(jq -r '.renamed | length' "$LATEST_JSON")" +} > "$LATEST_TXT" +``` + +- [ ] **Step 4: Ignore tracking artifacts in git** + +Append this line to `.gitignore`: + +```gitignore +.tracking/ +``` + +- [ ] **Step 5: Run test to verify pass** + +Run: `bash scripts/tests/test-track-git-status.sh` +Expected: PASS (exit code 0). + +- [ ] **Step 6: Commit** + +```bash +git add .gitignore scripts/track-git-status.sh scripts/tests/test-track-git-status.sh +git commit -m "feat: add git status collector and artifact snapshots" +``` + +--- + +### Task 2: Add collector safeguards (rotation + non-blocking behavior) + +**Files:** +- Modify: `scripts/tests/test-track-git-status.sh` +- Modify: `scripts/track-git-status.sh` + +- [ ] **Step 1: Add failing tests for rotation and malformed input tolerance** + +Add to `scripts/tests/test-track-git-status.sh`: + +```bash +# rotation test +python3 - <<'PY' +from pathlib import Path +p = Path(".tmp-history") +p.mkdir(exist_ok=True) +(p/"history.ndjson").write_text("x"*120) +PY +"$ROOT/scripts/track-git-status.sh" \ + --repo-root "$ROOT" \ + --branch "main" \ + --porcelain-file "$TMP/porcelain.txt" \ + --tracking-dir ".tmp-history" \ + TRACKING_MAX_BYTES=10 +test -f .tmp-history/history.ndjson +ls .tmp-history/history.*.ndjson >/dev/null +rm -rf .tmp-history +``` + +- [ ] **Step 2: Run test to verify failure** + +Run: `bash scripts/tests/test-track-git-status.sh` +Expected: FAIL until environment/rotation handling is corrected. + +- [ ] **Step 3: Implement minimal fix for configurable rotation threshold and robust empty arrays** + +Update `scripts/track-git-status.sh` to: + +```bash +MAX_BYTES="${TRACKING_MAX_BYTES:-10485760}" + +to_json_array() { + if [[ $# -eq 0 ]]; then + printf '[]' + else + printf '%s\n' "$@" | jq -Rsc 'split("\n")[:-1]' + fi +} +``` + +and replace the four `--argjson ...` generators with `to_json_array`. + +- [ ] **Step 4: Re-run test to verify pass** + +Run: `bash scripts/tests/test-track-git-status.sh` +Expected: PASS. + +- [ ] **Step 5: Commit** + +```bash +git add scripts/track-git-status.sh scripts/tests/test-track-git-status.sh +git commit -m "fix: harden collector rotation and array handling" +``` + +--- + +### Task 3: Add transparent git shim and installer (ROS parent only) + +**Files:** +- Create: `session/docs/snippets/git-tracking-shim.bash` +- Create: `scripts/install-git-tracking-shim.sh` +- Create: `scripts/tests/test-git-tracking-shim.sh` + +- [ ] **Step 1: Write failing shim-routing test** + +```bash +#!/usr/bin/env bash +set -euo pipefail + +ROOT="/mnt/data/ros" +TMP="$(mktemp -d)" +trap 'rm -rf "$TMP"' EXIT + +cat > "$TMP/fake-git" <<'EOF' +#!/usr/bin/env bash +echo "REAL_GIT $*" >> "$TMP/out.log" +EOF +chmod +x "$TMP/fake-git" + +export REAL_GIT_BIN="$TMP/fake-git" +export TRACKER_SCRIPT="$ROOT/scripts/track-git-status.sh" +source "$ROOT/session/docs/snippets/git-tracking-shim.bash" + +git status +grep -q "REAL_GIT status" "$TMP/out.log" +``` + +- [ ] **Step 2: Run test to verify failure** + +Run: `bash scripts/tests/test-git-tracking-shim.sh` +Expected: FAIL because shim snippet does not exist yet. + +- [ ] **Step 3: Implement shim snippet** + +`session/docs/snippets/git-tracking-shim.bash`: + +```bash +git() { + local real_git="${REAL_GIT_BIN:-/usr/bin/git}" + local tracker="${TRACKER_SCRIPT:-/mnt/data/ros/scripts/track-git-status.sh}" + local cmd="${1:-}" + + if [[ "$cmd" == "status" || "$cmd" == "st" ]]; then + local top + top="$("$real_git" rev-parse --show-toplevel 2>/dev/null || true)" + if [[ "$top" == "/mnt/data/ros" ]]; then + local tmp porcelain branch + tmp="$(mktemp)" + porcelain="$tmp.porcelain" + branch="$("$real_git" -C "$top" branch --show-current 2>/dev/null || echo unknown)" + "$real_git" -C "$top" status --porcelain=v1 > "$porcelain" || true + if ! "$tracker" --repo-root "$top" --branch "$branch" --porcelain-file "$porcelain" --tracking-dir "$top/.tracking"; then + echo "[tracking-warning] failed to write tracking artifacts" >&2 + fi + rm -f "$tmp" "$porcelain" + fi + fi + "$real_git" "$@" +} +``` + +- [ ] **Step 4: Implement installer helper** + +`scripts/install-git-tracking-shim.sh`: + +```bash +#!/usr/bin/env bash +set -euo pipefail + +BASHRC="${HOME}/.bashrc" +MARK_START="# >>> ros git tracking shim >>>" +MARK_END="# <<< ros git tracking shim <<<" +SNIPPET="/mnt/data/ros/session/docs/snippets/git-tracking-shim.bash" + +touch "$BASHRC" +if grep -q "$MARK_START" "$BASHRC"; then + exit 0 +fi + +{ + echo "$MARK_START" + echo "[ -f \"$SNIPPET\" ] && source \"$SNIPPET\"" + echo "$MARK_END" +} >> "$BASHRC" +``` + +- [ ] **Step 5: Run shim test to verify pass** + +Run: `bash scripts/tests/test-git-tracking-shim.sh` +Expected: PASS. + +- [ ] **Step 6: Commit** + +```bash +git add session/docs/snippets/git-tracking-shim.bash scripts/install-git-tracking-shim.sh scripts/tests/test-git-tracking-shim.sh +git commit -m "feat: add transparent git status tracking shim and installer" +``` + +--- + +### Task 4: Install + end-to-end verification in ROS parent repo + +**Files:** +- Modify: none (runtime verification and shell setup) + +- [ ] **Step 1: Install shim idempotently** + +Run: + +```bash +bash /mnt/data/ros/scripts/install-git-tracking-shim.sh +source ~/.bashrc +``` + +Expected: no duplicate shim block entries. + +- [ ] **Step 2: Create representative file-state changes for validation** + +Run: + +```bash +cd /mnt/data/ros +echo "tmp" > .tracking-e2e-untracked.tmp +touch .tracking-e2e-modified.tmp && git add .tracking-e2e-modified.tmp && echo "m" >> .tracking-e2e-modified.tmp +``` + +- [ ] **Step 3: Trigger tracking through git status** + +Run: + +```bash +git status +``` + +Expected: +- `.tracking/latest.json` exists +- `.tracking/history.ndjson` appended +- `.tracking/latest.txt` updated + +- [ ] **Step 4: Validate tracker does not run in submodule** + +Run: + +```bash +cd /mnt/data/ros/program/benchmark-core +git status +test ! -d .tracking +``` + +Expected: PASS (no local `.tracking` folder in submodule). + +- [ ] **Step 5: Cleanup temporary e2e files** + +Run: + +```bash +cd /mnt/data/ros +git restore --staged .tracking-e2e-modified.tmp || true +rm -f .tracking-e2e-untracked.tmp .tracking-e2e-modified.tmp +``` + +- [ ] **Step 6: Commit final operational docs note (if needed)** + +If README operational note is added: + +```bash +git add README.md +git commit -m "docs: add git tracking shim usage note" +``` + +--- + +## Spec Coverage Check (self-review) + +1. **ROS parent only:** Covered via strict top-level check in shim (Task 3). +2. **Track untracked/modified/deleted/renamed:** Covered in collector parsing (Task 1). +3. **Append history + latest snapshot + text summary:** Covered in artifact writes (Task 1). +4. **Non-blocking behavior:** Covered via warning + passthrough (Task 3). +5. **Rotation policy:** Covered in Task 2. +6. **Submodule exclusion:** Covered in Task 4 explicit check. +7. **No placeholders:** All file paths, code, and commands are explicit. + From 0641af6fe5890bd4ee5d83dbbb7319a9b03ef591 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sat, 2 May 2026 20:14:22 +0300 Subject: [PATCH 03/33] feat: add git status collector and artifact snapshots Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .gitignore | 1 + scripts/tests/test-track-git-status.sh | 41 +++++++++++ scripts/track-git-status.sh | 98 ++++++++++++++++++++++++++ 3 files changed, 140 insertions(+) create mode 100755 scripts/tests/test-track-git-status.sh create mode 100755 scripts/track-git-status.sh diff --git a/.gitignore b/.gitignore index e458ed5..fc44c28 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ .worktrees/ +.tracking/ diff --git a/scripts/tests/test-track-git-status.sh b/scripts/tests/test-track-git-status.sh new file mode 100755 index 0000000..9319123 --- /dev/null +++ b/scripts/tests/test-track-git-status.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +WORK="$ROOT/scripts/tests/.tmp-track-git-status" +SCRIPT="$ROOT/scripts/track-git-status.sh" + +rm -rf "$WORK" +mkdir -p "$WORK" +trap 'rm -rf "$WORK"' EXIT + +cat > "$WORK/porcelain.txt" <<'PORCELAIN' +?? new.txt + M changed.md + D removed.log +R old.py -> new.py +PORCELAIN + +if [[ -x "$SCRIPT" ]]; then + "$SCRIPT" \ + --repo-root "$ROOT" \ + --branch "main" \ + --porcelain-file "$WORK/porcelain.txt" \ + --tracking-dir "$WORK/.tracking" +fi + +test -f "$WORK/.tracking/latest.json" +test -f "$WORK/.tracking/history.ndjson" +test -f "$WORK/.tracking/latest.txt" + +jq -e '.untracked == ["new.txt"]' "$WORK/.tracking/latest.json" >/dev/null +jq -e '.modified == ["changed.md"]' "$WORK/.tracking/latest.json" >/dev/null +jq -e '.deleted == ["removed.log"]' "$WORK/.tracking/latest.json" >/dev/null +jq -e '.renamed == ["old.py -> new.py"]' "$WORK/.tracking/latest.json" >/dev/null + +jq -e '.untracked == ["new.txt"]' "$WORK/.tracking/history.ndjson" >/dev/null + +grep -q '^untracked: 1$' "$WORK/.tracking/latest.txt" +grep -q '^modified: 1$' "$WORK/.tracking/latest.txt" +grep -q '^deleted: 1$' "$WORK/.tracking/latest.txt" +grep -q '^renamed: 1$' "$WORK/.tracking/latest.txt" diff --git a/scripts/track-git-status.sh b/scripts/track-git-status.sh new file mode 100755 index 0000000..0a17883 --- /dev/null +++ b/scripts/track-git-status.sh @@ -0,0 +1,98 @@ +#!/usr/bin/env bash +set -euo pipefail + +REPO_ROOT="" +BRANCH="" +PORCELAIN_FILE="" +TRACKING_DIR="" + +while [[ $# -gt 0 ]]; do + case "$1" in + --repo-root) + REPO_ROOT="$2" + shift 2 + ;; + --branch) + BRANCH="$2" + shift 2 + ;; + --porcelain-file) + PORCELAIN_FILE="$2" + shift 2 + ;; + --tracking-dir) + TRACKING_DIR="$2" + shift 2 + ;; + *) + echo "Unknown arg: $1" >&2 + exit 2 + ;; + esac +done + +if [[ -z "$REPO_ROOT" || -z "$BRANCH" || -z "$PORCELAIN_FILE" || -z "$TRACKING_DIR" ]]; then + echo "Missing required args" >&2 + exit 2 +fi + +mkdir -p "$TRACKING_DIR" +LATEST_JSON="$TRACKING_DIR/latest.json" +HISTORY="$TRACKING_DIR/history.ndjson" +LATEST_TXT="$TRACKING_DIR/latest.txt" + +UNTRACKED=() +MODIFIED=() +DELETED=() +RENAMED=() + +while IFS= read -r line; do + [[ -z "$line" ]] && continue + + if [[ "$line" == '?? '* ]]; then + UNTRACKED+=("${line:3}") + continue + fi + + status="${line:0:2}" + path="${line:3}" + x="${status:0:1}" + y="${status:1:1}" + + if [[ "$x" == "R" || "$y" == "R" ]]; then + RENAMED+=("$path") + fi + if [[ "$x" == "D" || "$y" == "D" ]]; then + DELETED+=("$path") + fi + if [[ "$x" == "M" || "$y" == "M" ]]; then + MODIFIED+=("$path") + fi +done < "$PORCELAIN_FILE" + +json_array() { + printf '%s\n' "$@" | jq -Rsc 'if . == "\n" then [] else split("\n")[:-1] end' +} + +json="$(jq -cn \ + --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ + --arg repo "$REPO_ROOT" \ + --arg branch "$BRANCH" \ + --argjson untracked "$(json_array "${UNTRACKED[@]}")" \ + --argjson modified "$(json_array "${MODIFIED[@]}")" \ + --argjson deleted "$(json_array "${DELETED[@]}")" \ + --argjson renamed "$(json_array "${RENAMED[@]}")" \ + '{timestamp:$ts,repo_root:$repo,branch:$branch,untracked:$untracked,modified:$modified,deleted:$deleted,renamed:$renamed}')" + +printf '%s\n' "$json" > "$LATEST_JSON" +printf '%s\n' "$json" >> "$HISTORY" + +{ + echo "timestamp: $(jq -r '.timestamp' "$LATEST_JSON")" + echo "repo: $(jq -r '.repo_root' "$LATEST_JSON")" + echo "branch: $(jq -r '.branch' "$LATEST_JSON")" + echo "untracked: $(jq -r '.untracked | length' "$LATEST_JSON")" + echo "modified: $(jq -r '.modified | length' "$LATEST_JSON")" + echo "deleted: $(jq -r '.deleted | length' "$LATEST_JSON")" + echo "renamed: $(jq -r '.renamed | length' "$LATEST_JSON")" +} > "$LATEST_TXT" From ac7014b8c4625fef90c57f58c49b87c859de332b Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sat, 2 May 2026 20:18:14 +0300 Subject: [PATCH 04/33] fix: harden collector rotation and array handling Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scripts/tests/test-track-git-status.sh | 30 ++++++++++++++++++++++++++ scripts/track-git-status.sh | 24 +++++++++++++++------ 2 files changed, 48 insertions(+), 6 deletions(-) diff --git a/scripts/tests/test-track-git-status.sh b/scripts/tests/test-track-git-status.sh index 9319123..0bbead7 100755 --- a/scripts/tests/test-track-git-status.sh +++ b/scripts/tests/test-track-git-status.sh @@ -39,3 +39,33 @@ grep -q '^untracked: 1$' "$WORK/.tracking/latest.txt" grep -q '^modified: 1$' "$WORK/.tracking/latest.txt" grep -q '^deleted: 1$' "$WORK/.tracking/latest.txt" grep -q '^renamed: 1$' "$WORK/.tracking/latest.txt" + +ROTATION_DIR="$WORK/.rotation" +mkdir -p "$ROTATION_DIR" +python3 - "$ROTATION_DIR/history.ndjson" <<'PY' +from pathlib import Path +import sys + +Path(sys.argv[1]).write_text("x" * 120, encoding="utf-8") +PY + +TRACKING_MAX_BYTES=10 "$SCRIPT" \ + --repo-root "$ROOT" \ + --branch "main" \ + --porcelain-file "$WORK/porcelain.txt" \ + --tracking-dir "$ROTATION_DIR" + +test -f "$ROTATION_DIR/history.ndjson" +ls "$ROTATION_DIR"/history.*.ndjson >/dev/null + +: > "$WORK/porcelain-empty.txt" +"$SCRIPT" \ + --repo-root "$ROOT" \ + --branch "main" \ + --porcelain-file "$WORK/porcelain-empty.txt" \ + --tracking-dir "$WORK/.tracking-empty" + +jq -e '.untracked == []' "$WORK/.tracking-empty/latest.json" >/dev/null +jq -e '.modified == []' "$WORK/.tracking-empty/latest.json" >/dev/null +jq -e '.deleted == []' "$WORK/.tracking-empty/latest.json" >/dev/null +jq -e '.renamed == []' "$WORK/.tracking-empty/latest.json" >/dev/null diff --git a/scripts/track-git-status.sh b/scripts/track-git-status.sh index 0a17883..c9f81ae 100755 --- a/scripts/track-git-status.sh +++ b/scripts/track-git-status.sh @@ -5,6 +5,7 @@ REPO_ROOT="" BRANCH="" PORCELAIN_FILE="" TRACKING_DIR="" +MAX_BYTES="${TRACKING_MAX_BYTES:-10485760}" while [[ $# -gt 0 ]]; do case "$1" in @@ -41,6 +42,13 @@ LATEST_JSON="$TRACKING_DIR/latest.json" HISTORY="$TRACKING_DIR/history.ndjson" LATEST_TXT="$TRACKING_DIR/latest.txt" +if [[ -f "$HISTORY" ]]; then + size="$(wc -c < "$HISTORY" | tr -d '[:space:]')" + if [[ "$size" -gt "$MAX_BYTES" ]]; then + mv "$HISTORY" "$TRACKING_DIR/history.$(date -u +%Y%m%dT%H%M%SZ).ndjson" + fi +fi + UNTRACKED=() MODIFIED=() DELETED=() @@ -70,18 +78,22 @@ while IFS= read -r line; do fi done < "$PORCELAIN_FILE" -json_array() { - printf '%s\n' "$@" | jq -Rsc 'if . == "\n" then [] else split("\n")[:-1] end' +to_json_array() { + if [[ $# -eq 0 ]]; then + printf '[]' + else + printf '%s\n' "$@" | jq -Rsc 'split("\n")[:-1]' + fi } json="$(jq -cn \ --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ --arg repo "$REPO_ROOT" \ --arg branch "$BRANCH" \ - --argjson untracked "$(json_array "${UNTRACKED[@]}")" \ - --argjson modified "$(json_array "${MODIFIED[@]}")" \ - --argjson deleted "$(json_array "${DELETED[@]}")" \ - --argjson renamed "$(json_array "${RENAMED[@]}")" \ + --argjson untracked "$(to_json_array "${UNTRACKED[@]}")" \ + --argjson modified "$(to_json_array "${MODIFIED[@]}")" \ + --argjson deleted "$(to_json_array "${DELETED[@]}")" \ + --argjson renamed "$(to_json_array "${RENAMED[@]}")" \ '{timestamp:$ts,repo_root:$repo,branch:$branch,untracked:$untracked,modified:$modified,deleted:$deleted,renamed:$renamed}')" printf '%s\n' "$json" > "$LATEST_JSON" From 575d75b53f614f57977bc462b0c065a5ab1f4fee Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sat, 2 May 2026 20:22:09 +0300 Subject: [PATCH 05/33] fix: prevent rotation filename collisions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scripts/tests/test-track-git-status.sh | 46 ++++++++++++++++++++++++++ scripts/track-git-status.sh | 11 +++++- 2 files changed, 56 insertions(+), 1 deletion(-) diff --git a/scripts/tests/test-track-git-status.sh b/scripts/tests/test-track-git-status.sh index 0bbead7..940c010 100755 --- a/scripts/tests/test-track-git-status.sh +++ b/scripts/tests/test-track-git-status.sh @@ -58,6 +58,52 @@ TRACKING_MAX_BYTES=10 "$SCRIPT" \ test -f "$ROTATION_DIR/history.ndjson" ls "$ROTATION_DIR"/history.*.ndjson >/dev/null +FAKE_BIN="$WORK/fake-bin" +mkdir -p "$FAKE_BIN" +cat > "$FAKE_BIN/date" <<'SH' +#!/usr/bin/env bash +if [[ "${1:-}" == "-u" ]]; then + shift +fi + +case "${1:-}" in + +%Y%m%dT%H%M%SZ) + printf '20000101T000000Z\n' + ;; + +%Y-%m-%dT%H:%M:%SZ) + printf '2000-01-01T00:00:00Z\n' + ;; + *) + /usr/bin/date -u "${1:-}" + ;; +esac +SH +chmod +x "$FAKE_BIN/date" + +COLLISION_DIR="$WORK/.rotation-collision" +mkdir -p "$COLLISION_DIR" +python3 - "$COLLISION_DIR/history.ndjson" <<'PY' +from pathlib import Path +import sys + +Path(sys.argv[1]).write_text("x" * 120, encoding="utf-8") +PY + +PATH="$FAKE_BIN:$PATH" TRACKING_MAX_BYTES=10 "$SCRIPT" \ + --repo-root "$ROOT" \ + --branch "main" \ + --porcelain-file "$WORK/porcelain.txt" \ + --tracking-dir "$COLLISION_DIR" + +PATH="$FAKE_BIN:$PATH" TRACKING_MAX_BYTES=10 "$SCRIPT" \ + --repo-root "$ROOT" \ + --branch "main" \ + --porcelain-file "$WORK/porcelain.txt" \ + --tracking-dir "$COLLISION_DIR" + +mapfile -t ROTATED_FILES < <(find "$COLLISION_DIR" -maxdepth 1 -type f -name 'history.*.ndjson' | sort) +test "${#ROTATED_FILES[@]}" -eq 2 + : > "$WORK/porcelain-empty.txt" "$SCRIPT" \ --repo-root "$ROOT" \ diff --git a/scripts/track-git-status.sh b/scripts/track-git-status.sh index c9f81ae..f486043 100755 --- a/scripts/track-git-status.sh +++ b/scripts/track-git-status.sh @@ -45,7 +45,16 @@ LATEST_TXT="$TRACKING_DIR/latest.txt" if [[ -f "$HISTORY" ]]; then size="$(wc -c < "$HISTORY" | tr -d '[:space:]')" if [[ "$size" -gt "$MAX_BYTES" ]]; then - mv "$HISTORY" "$TRACKING_DIR/history.$(date -u +%Y%m%dT%H%M%SZ).ndjson" + rotation_ts="$(date -u +%Y%m%dT%H%M%SZ)" + rotation_ns="$(date -u +%N)" + rotation_base="$TRACKING_DIR/history.${rotation_ts}.${rotation_ns}.$$" + rotation_target="${rotation_base}.ndjson" + rotation_index=0 + while [[ -e "$rotation_target" ]]; do + rotation_index=$((rotation_index + 1)) + rotation_target="${rotation_base}.${rotation_index}.ndjson" + done + mv "$HISTORY" "$rotation_target" fi fi From c5c4809f175d344e63f937e05b393a1abafa292f Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sat, 2 May 2026 20:25:59 +0300 Subject: [PATCH 06/33] fix: serialize history rotation and append Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scripts/tests/test-track-git-status.sh | 36 +++++++++++++++++++ scripts/track-git-status.sh | 48 ++++++++++++++++---------- 2 files changed, 66 insertions(+), 18 deletions(-) diff --git a/scripts/tests/test-track-git-status.sh b/scripts/tests/test-track-git-status.sh index 940c010..0ddf34f 100755 --- a/scripts/tests/test-track-git-status.sh +++ b/scripts/tests/test-track-git-status.sh @@ -104,6 +104,42 @@ PATH="$FAKE_BIN:$PATH" TRACKING_MAX_BYTES=10 "$SCRIPT" \ mapfile -t ROTATED_FILES < <(find "$COLLISION_DIR" -maxdepth 1 -type f -name 'history.*.ndjson' | sort) test "${#ROTATED_FILES[@]}" -eq 2 +CONCURRENT_DIR="$WORK/.concurrent-rotation" +mkdir -p "$CONCURRENT_DIR" +python3 - "$CONCURRENT_DIR/history.ndjson" <<'PY' +from pathlib import Path +import sys + +Path(sys.argv[1]).write_text("x" * 20000, encoding="utf-8") +PY + +RUNS=16 +set +e +for i in $(seq 1 "$RUNS"); do + ( + TRACKING_MAX_BYTES=10000 "$SCRIPT" \ + --repo-root "$ROOT" \ + --branch "main" \ + --porcelain-file "$WORK/porcelain.txt" \ + --tracking-dir "$CONCURRENT_DIR" \ + >/dev/null 2>"$CONCURRENT_DIR/err.$i" + echo $? > "$CONCURRENT_DIR/rc.$i" + ) & +done +wait +set -e + +FAILS=0 +for i in $(seq 1 "$RUNS"); do + rc="$(cat "$CONCURRENT_DIR/rc.$i")" + if [[ "$rc" -ne 0 ]]; then + FAILS=$((FAILS + 1)) + fi +done + +test "$FAILS" -eq 0 +test "$(wc -l < "$CONCURRENT_DIR/history.ndjson")" -eq "$RUNS" + : > "$WORK/porcelain-empty.txt" "$SCRIPT" \ --repo-root "$ROOT" \ diff --git a/scripts/track-git-status.sh b/scripts/track-git-status.sh index f486043..1e0e4ae 100755 --- a/scripts/track-git-status.sh +++ b/scripts/track-git-status.sh @@ -41,22 +41,7 @@ mkdir -p "$TRACKING_DIR" LATEST_JSON="$TRACKING_DIR/latest.json" HISTORY="$TRACKING_DIR/history.ndjson" LATEST_TXT="$TRACKING_DIR/latest.txt" - -if [[ -f "$HISTORY" ]]; then - size="$(wc -c < "$HISTORY" | tr -d '[:space:]')" - if [[ "$size" -gt "$MAX_BYTES" ]]; then - rotation_ts="$(date -u +%Y%m%dT%H%M%SZ)" - rotation_ns="$(date -u +%N)" - rotation_base="$TRACKING_DIR/history.${rotation_ts}.${rotation_ns}.$$" - rotation_target="${rotation_base}.ndjson" - rotation_index=0 - while [[ -e "$rotation_target" ]]; do - rotation_index=$((rotation_index + 1)) - rotation_target="${rotation_base}.${rotation_index}.ndjson" - done - mv "$HISTORY" "$rotation_target" - fi -fi +LOCK_FILE="$TRACKING_DIR/.history.lock" UNTRACKED=() MODIFIED=() @@ -105,8 +90,35 @@ json="$(jq -cn \ --argjson renamed "$(to_json_array "${RENAMED[@]}")" \ '{timestamp:$ts,repo_root:$repo,branch:$branch,untracked:$untracked,modified:$modified,deleted:$deleted,renamed:$renamed}')" -printf '%s\n' "$json" > "$LATEST_JSON" -printf '%s\n' "$json" >> "$HISTORY" +{ + flock -x 9 + + if [[ -f "$HISTORY" ]]; then + size="$(wc -c < "$HISTORY" | tr -d '[:space:]')" + if [[ "$size" -gt "$MAX_BYTES" ]]; then + rotation_ts="$(date -u +%Y%m%dT%H%M%SZ)" + rotation_ns="$(date -u +%N)" + rotation_base="$TRACKING_DIR/history.${rotation_ts}.${rotation_ns}.$$" + rotation_target="${rotation_base}.ndjson" + rotation_index=0 + while [[ -e "$rotation_target" ]]; do + rotation_index=$((rotation_index + 1)) + rotation_target="${rotation_base}.${rotation_index}.ndjson" + done + + if [[ -f "$HISTORY" ]]; then + if ! mv "$HISTORY" "$rotation_target"; then + if [[ -f "$HISTORY" ]]; then + exit 1 + fi + fi + fi + fi + fi + + printf '%s\n' "$json" > "$LATEST_JSON" + printf '%s\n' "$json" >> "$HISTORY" +} 9>>"$LOCK_FILE" { echo "timestamp: $(jq -r '.timestamp' "$LATEST_JSON")" From 598ce04f7e7fb3ab4f0b8ea5e51fbcb596704f7e Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sat, 2 May 2026 20:32:25 +0300 Subject: [PATCH 07/33] test: add git tracking shim behavior checks Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scripts/tests/test-git-tracking-shim.sh | 116 ++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100755 scripts/tests/test-git-tracking-shim.sh diff --git a/scripts/tests/test-git-tracking-shim.sh b/scripts/tests/test-git-tracking-shim.sh new file mode 100755 index 0000000..119fc9a --- /dev/null +++ b/scripts/tests/test-git-tracking-shim.sh @@ -0,0 +1,116 @@ +#!/usr/bin/env bash +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +TRACKED_ROOT="/mnt/data/ros" +TMP_BASE="$REPO_ROOT/scripts/tests/.tmp-git-shim-test-$$" +trap 'rm -rf "$TMP_BASE"' EXIT +mkdir -p "$TMP_BASE" + +REAL_GIT="$TMP_BASE/fake-git" +TRACKER="$TMP_BASE/fake-tracker.sh" +REAL_LOG="$TMP_BASE/real.log" +TRACKER_LOG="$TMP_BASE/tracker.log" + +cat > "$REAL_GIT" <<'FAKEGIT' +#!/usr/bin/env bash +set -euo pipefail +: "${REAL_LOG:?}" +if [[ "${1:-}" == "rev-parse" && "${2:-}" == "--show-toplevel" ]]; then + printf '%s\n' "${FAKE_TOPLEVEL:-$PWD}" + exit 0 +fi +if [[ "${1:-}" == "-C" && "${3:-}" == "branch" && "${4:-}" == "--show-current" ]]; then + printf '%s\n' "${FAKE_BRANCH:-main}" + exit 0 +fi +if [[ "${1:-}" == "-C" && "${3:-}" == "status" && "${4:-}" == "--porcelain=v1" ]]; then + printf '%s\n' "${FAKE_PORCELAIN_LINE:-?? new.txt}" + exit 0 +fi +printf 'REAL_GIT %s\n' "$*" >> "$REAL_LOG" +if [[ "${1:-}" == "status" || "${1:-}" == "st" ]]; then + printf 'REAL_STATUS\n' +fi +FAKEGIT +chmod +x "$REAL_GIT" + +cat > "$TRACKER" <<'FAKETRACKER' +#!/usr/bin/env bash +set -euo pipefail +: "${TRACKER_LOG:?}" +printf 'TRACKER %s\n' "$*" >> "$TRACKER_LOG" +if [[ "${TRACKER_FAIL:-0}" == "1" ]]; then + exit 7 +fi +FAKETRACKER +chmod +x "$TRACKER" + +export REAL_GIT_BIN="$REAL_GIT" +export TRACKER_SCRIPT="$TRACKER" +export REAL_LOG +export TRACKER_LOG +export FAKE_BRANCH="main" + +# RED trigger if shim does not exist yet. +# shellcheck disable=SC1091 +source "$REPO_ROOT/session/docs/snippets/git-tracking-shim.bash" + +: > "$REAL_LOG" +: > "$TRACKER_LOG" +FAKE_TOPLEVEL="$TRACKED_ROOT" git log --oneline >/dev/null + +grep -Fq "REAL_GIT log --oneline" "$REAL_LOG" +if [[ -s "$TRACKER_LOG" ]]; then + echo "tracker should not run for non-status commands" >&2 + exit 1 +fi + +: > "$REAL_LOG" +: > "$TRACKER_LOG" +FAKE_TOPLEVEL="$TRACKED_ROOT" git status >"$TMP_BASE/status.out" +grep -Fq "REAL_STATUS" "$TMP_BASE/status.out" +grep -Fq "REAL_GIT status" "$REAL_LOG" +grep -Fq "TRACKER --repo-root $TRACKED_ROOT --branch main" "$TRACKER_LOG" + +: > "$REAL_LOG" +: > "$TRACKER_LOG" +FAKE_TOPLEVEL="$TRACKED_ROOT" git st >/dev/null +grep -Fq "REAL_GIT st" "$REAL_LOG" +grep -Fq "TRACKER --repo-root $TRACKED_ROOT --branch main" "$TRACKER_LOG" + +: > "$REAL_LOG" +: > "$TRACKER_LOG" +TRACKER_FAIL=1 FAKE_TOPLEVEL="$TRACKED_ROOT" git status >"$TMP_BASE/fail.out" 2>"$TMP_BASE/fail.err" +grep -Fq "REAL_STATUS" "$TMP_BASE/fail.out" +grep -Fq "[tracking-warning] failed to write tracking artifacts" "$TMP_BASE/fail.err" +grep -Fq "REAL_GIT status" "$REAL_LOG" + +: > "$REAL_LOG" +: > "$TRACKER_LOG" +FAKE_TOPLEVEL="$TMP_BASE/not-ros" git status >/dev/null +grep -Fq "REAL_GIT status" "$REAL_LOG" +if [[ -s "$TRACKER_LOG" ]]; then + echo "tracker should not run outside tracked root" >&2 + exit 1 +fi + +ORIG_HOME="${HOME:-}" +export HOME="$TMP_BASE/home" +mkdir -p "$HOME" +: > "$HOME/.bashrc" + +"$REPO_ROOT/scripts/install-git-tracking-shim.sh" +"$REPO_ROOT/scripts/install-git-tracking-shim.sh" + +start_count="$(grep -Fc '# >>> ros git tracking shim >>>' "$HOME/.bashrc")" +end_count="$(grep -Fc '# <<< ros git tracking shim <<<' "$HOME/.bashrc")" +line_count="$(grep -Fc '[ -f "/mnt/data/ros/session/docs/snippets/git-tracking-shim.bash" ] && source "/mnt/data/ros/session/docs/snippets/git-tracking-shim.bash"' "$HOME/.bashrc")" + +[[ "$start_count" -eq 1 ]] +[[ "$end_count" -eq 1 ]] +[[ "$line_count" -eq 1 ]] + +if [[ -n "$ORIG_HOME" ]]; then + export HOME="$ORIG_HOME" +fi From 785fdb8aea2732337f5400bd5a0fc0af3a037900 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sat, 2 May 2026 20:32:56 +0300 Subject: [PATCH 08/33] feat: add transparent git status tracking shim and installer Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scripts/install-git-tracking-shim.sh | 20 +++++++++++ session/docs/snippets/git-tracking-shim.bash | 37 ++++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100755 scripts/install-git-tracking-shim.sh create mode 100644 session/docs/snippets/git-tracking-shim.bash diff --git a/scripts/install-git-tracking-shim.sh b/scripts/install-git-tracking-shim.sh new file mode 100755 index 0000000..ce9fa06 --- /dev/null +++ b/scripts/install-git-tracking-shim.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +set -euo pipefail + +BASHRC="${HOME}/.bashrc" +MARK_START="# >>> ros git tracking shim >>>" +MARK_END="# <<< ros git tracking shim <<<" +SNIPPET="/mnt/data/ros/session/docs/snippets/git-tracking-shim.bash" +SOURCE_LINE="[ -f \"$SNIPPET\" ] && source \"$SNIPPET\"" + +touch "$BASHRC" + +if grep -Fq "$MARK_START" "$BASHRC"; then + exit 0 +fi + +{ + printf '%s\n' "$MARK_START" + printf '%s\n' "$SOURCE_LINE" + printf '%s\n' "$MARK_END" +} >> "$BASHRC" diff --git a/session/docs/snippets/git-tracking-shim.bash b/session/docs/snippets/git-tracking-shim.bash new file mode 100644 index 0000000..ce290d6 --- /dev/null +++ b/session/docs/snippets/git-tracking-shim.bash @@ -0,0 +1,37 @@ +git() { + local real_git tracker tracked_root cmd + real_git="${REAL_GIT_BIN:-/usr/bin/git}" + tracker="${TRACKER_SCRIPT:-/mnt/data/ros/scripts/track-git-status.sh}" + tracked_root="/mnt/data/ros" + cmd="${1:-}" + + if [[ "$cmd" == "status" || "$cmd" == "st" ]]; then + local top + top="$("$real_git" rev-parse --show-toplevel 2>/dev/null || true)" + + if [[ "$top" == "$tracked_root" ]]; then + local tracking_dir branch porcelain_file + tracking_dir="$top/.tracking" + branch="$("$real_git" -C "$top" branch --show-current 2>/dev/null || printf 'unknown')" + porcelain_file="$tracking_dir/.git-status-porcelain.$$.$RANDOM" + + mkdir -p "$tracking_dir" + if ! "$real_git" -C "$top" status --porcelain=v1 >"$porcelain_file" 2>/dev/null; then + : >"$porcelain_file" + fi + + if ! "$tracker" \ + --repo-root "$top" \ + --branch "$branch" \ + --porcelain-file "$porcelain_file" \ + --tracking-dir "$tracking_dir" \ + >/dev/null 2>&1; then + printf '[tracking-warning] failed to write tracking artifacts\n' >&2 + fi + + rm -f "$porcelain_file" + fi + fi + + "$real_git" "$@" +} From 4bc39b67fe0a4810c22c88944331ad49f70ba5a9 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sat, 2 May 2026 20:37:19 +0300 Subject: [PATCH 09/33] fix: harden git shim command routing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scripts/tests/test-git-tracking-shim.sh | 36 ++++++++ session/docs/snippets/git-tracking-shim.bash | 92 +++++++++++++++++++- 2 files changed, 125 insertions(+), 3 deletions(-) diff --git a/scripts/tests/test-git-tracking-shim.sh b/scripts/tests/test-git-tracking-shim.sh index 119fc9a..99cbf68 100755 --- a/scripts/tests/test-git-tracking-shim.sh +++ b/scripts/tests/test-git-tracking-shim.sh @@ -8,14 +8,22 @@ trap 'rm -rf "$TMP_BASE"' EXIT mkdir -p "$TMP_BASE" REAL_GIT="$TMP_BASE/fake-git" +BIN_DIR="$TMP_BASE/bin" TRACKER="$TMP_BASE/fake-tracker.sh" REAL_LOG="$TMP_BASE/real.log" TRACKER_LOG="$TMP_BASE/tracker.log" +WARN_LOG="$TMP_BASE/warn.log" + +mkdir -p "$BIN_DIR" cat > "$REAL_GIT" <<'FAKEGIT' #!/usr/bin/env bash set -euo pipefail : "${REAL_LOG:?}" +if [[ "${1:-}" == "-C" && "${3:-}" == "rev-parse" && "${4:-}" == "--show-toplevel" ]]; then + printf '%s\n' "${FAKE_TOPLEVEL:-$2}" + exit 0 +fi if [[ "${1:-}" == "rev-parse" && "${2:-}" == "--show-toplevel" ]]; then printf '%s\n' "${FAKE_TOPLEVEL:-$PWD}" exit 0 @@ -29,11 +37,15 @@ if [[ "${1:-}" == "-C" && "${3:-}" == "status" && "${4:-}" == "--porcelain=v1" ] exit 0 fi printf 'REAL_GIT %s\n' "$*" >> "$REAL_LOG" +if [[ "${1:-}" == "-C" && ( "${3:-}" == "status" || "${3:-}" == "st" ) ]]; then + printf 'REAL_STATUS\n' +fi if [[ "${1:-}" == "status" || "${1:-}" == "st" ]]; then printf 'REAL_STATUS\n' fi FAKEGIT chmod +x "$REAL_GIT" +cp "$REAL_GIT" "$BIN_DIR/git" cat > "$TRACKER" <<'FAKETRACKER' #!/usr/bin/env bash @@ -51,6 +63,7 @@ export TRACKER_SCRIPT="$TRACKER" export REAL_LOG export TRACKER_LOG export FAKE_BRANCH="main" +export PATH="$BIN_DIR:$PATH" # RED trigger if shim does not exist yet. # shellcheck disable=SC1091 @@ -79,6 +92,29 @@ FAKE_TOPLEVEL="$TRACKED_ROOT" git st >/dev/null grep -Fq "REAL_GIT st" "$REAL_LOG" grep -Fq "TRACKER --repo-root $TRACKED_ROOT --branch main" "$TRACKER_LOG" +: > "$REAL_LOG" +: > "$TRACKER_LOG" +FAKE_TOPLEVEL="$TRACKED_ROOT" git -C "$TRACKED_ROOT" status >"$TMP_BASE/status-with-global.out" +grep -Fq "REAL_STATUS" "$TMP_BASE/status-with-global.out" +grep -Fq "REAL_GIT -C $TRACKED_ROOT status" "$REAL_LOG" +grep -Fq "TRACKER --repo-root $TRACKED_ROOT --branch main" "$TRACKER_LOG" + +: > "$REAL_LOG" +: > "$TRACKER_LOG" +: > "$WARN_LOG" +REAL_GIT_BIN="git" FAKE_TOPLEVEL="$TRACKED_ROOT" git status >"$TMP_BASE/status-real-git-bin-git.out" 2>"$WARN_LOG" +grep -Fq "REAL_STATUS" "$TMP_BASE/status-real-git-bin-git.out" +grep -Fq "REAL_GIT status" "$REAL_LOG" +grep -Fq "unsafe REAL_GIT_BIN value: git" "$WARN_LOG" + +: > "$REAL_LOG" +: > "$TRACKER_LOG" +: > "$WARN_LOG" +REAL_GIT_BIN="fake-git" FAKE_TOPLEVEL="$TRACKED_ROOT" git status >"$TMP_BASE/status-real-git-bin-relative.out" 2>"$WARN_LOG" +grep -Fq "REAL_STATUS" "$TMP_BASE/status-real-git-bin-relative.out" +grep -Fq "REAL_GIT status" "$REAL_LOG" +grep -Fq "unsafe REAL_GIT_BIN value: fake-git" "$WARN_LOG" + : > "$REAL_LOG" : > "$TRACKER_LOG" TRACKER_FAIL=1 FAKE_TOPLEVEL="$TRACKED_ROOT" git status >"$TMP_BASE/fail.out" 2>"$TMP_BASE/fail.err" diff --git a/session/docs/snippets/git-tracking-shim.bash b/session/docs/snippets/git-tracking-shim.bash index ce290d6..ef0dc0f 100644 --- a/session/docs/snippets/git-tracking-shim.bash +++ b/session/docs/snippets/git-tracking-shim.bash @@ -1,13 +1,99 @@ +_git_tracking_resolve_real_git_bin() { + local configured resolved + configured="${REAL_GIT_BIN:-}" + + if [[ -n "$configured" ]]; then + if [[ "$configured" != /* ]]; then + printf '[tracking-warning] unsafe REAL_GIT_BIN value: %s\n' "$configured" >&2 + elif [[ ! -x "$configured" ]]; then + printf '[tracking-warning] REAL_GIT_BIN is not executable: %s\n' "$configured" >&2 + else + printf '%s\n' "$configured" + return + fi + fi + + resolved="$(type -P git 2>/dev/null || true)" + if [[ -z "$resolved" || ! -x "$resolved" ]]; then + resolved="/usr/bin/git" + fi + printf '%s\n' "$resolved" +} + +_git_tracking_effective_command() { + local arg + while (($#)); do + arg="$1" + case "$arg" in + --) + shift + printf '%s\n' "${1:-}" + return + ;; + -C|-c|--exec-path|--git-dir|--work-tree|--namespace|--super-prefix|--config-env) + shift 2 + ;; + --exec-path=*|--git-dir=*|--work-tree=*|--namespace=*|--super-prefix=*|--config-env=*|--list-cmds=*|\ + -p|--paginate|--no-pager|--no-replace-objects|--bare|--literal-pathspecs|--no-literal-pathspecs|\ + --glob-pathspecs|--noglob-pathspecs|--icase-pathspecs) + shift + ;; + -*) + shift + ;; + *) + printf '%s\n' "$arg" + return + ;; + esac + done +} + +_git_tracking_global_args() { + local arg + while (($#)); do + arg="$1" + case "$arg" in + --) + return + ;; + -C|-c|--exec-path|--git-dir|--work-tree|--namespace|--super-prefix|--config-env) + printf '%s\n' "$arg" + shift + if (($#)); then + printf '%s\n' "$1" + fi + shift + ;; + --exec-path=*|--git-dir=*|--work-tree=*|--namespace=*|--super-prefix=*|--config-env=*|--list-cmds=*|\ + -p|--paginate|--no-pager|--no-replace-objects|--bare|--literal-pathspecs|--no-literal-pathspecs|\ + --glob-pathspecs|--noglob-pathspecs|--icase-pathspecs) + printf '%s\n' "$arg" + shift + ;; + -*) + printf '%s\n' "$arg" + shift + ;; + *) + return + ;; + esac + done +} + git() { local real_git tracker tracked_root cmd - real_git="${REAL_GIT_BIN:-/usr/bin/git}" + local -a global_args + real_git="$(_git_tracking_resolve_real_git_bin)" tracker="${TRACKER_SCRIPT:-/mnt/data/ros/scripts/track-git-status.sh}" tracked_root="/mnt/data/ros" - cmd="${1:-}" + cmd="$(_git_tracking_effective_command "$@")" + mapfile -t global_args < <(_git_tracking_global_args "$@") if [[ "$cmd" == "status" || "$cmd" == "st" ]]; then local top - top="$("$real_git" rev-parse --show-toplevel 2>/dev/null || true)" + top="$("$real_git" "${global_args[@]}" rev-parse --show-toplevel 2>/dev/null || true)" if [[ "$top" == "$tracked_root" ]]; then local tracking_dir branch porcelain_file From da95f33f2a317a1885e136146752690041affedd Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sun, 3 May 2026 19:25:15 +0300 Subject: [PATCH 10/33] test: fix concurrent rotation temp cleanup race Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scripts/tests/test-track-git-status.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/tests/test-track-git-status.sh b/scripts/tests/test-track-git-status.sh index 0ddf34f..f914b9f 100755 --- a/scripts/tests/test-track-git-status.sh +++ b/scripts/tests/test-track-git-status.sh @@ -2,7 +2,7 @@ set -euo pipefail ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" -WORK="$ROOT/scripts/tests/.tmp-track-git-status" +WORK="$ROOT/scripts/tests/.tmp-track-git-status.$$.$RANDOM" SCRIPT="$ROOT/scripts/track-git-status.sh" rm -rf "$WORK" From 64ac64b66eaff8118eb9cba78ed19f44c6d658e8 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sun, 3 May 2026 19:41:28 +0300 Subject: [PATCH 11/33] docs(spec): add master README guidance design Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ...026-05-03-master-readme-guidance-design.md | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md diff --git a/docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md b/docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md new file mode 100644 index 0000000..6522de2 --- /dev/null +++ b/docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md @@ -0,0 +1,81 @@ +# Master README Guidance Design + +## Objective +Create a comprehensive, professional, command-driven root README for the ROS parent repository that guides users through onboarding and day-2 operations across the multi-repo structure. + +## Scope +- In scope: + - Rewrite `/mnt/data/ros/README.md`. + - Cover parent repo architecture and role of each `program/*` subrepo. + - Provide step-by-step commands for setup, operations, troubleshooting, and contribution workflow. + - Include verification checkpoints and expected outcomes after key commands. + - Link to deeper references in `docs/superpowers/` and `session/docs/`. +- Out of scope: + - Rewriting READMEs in every subrepo. + - Refactoring code or changing runtime behavior. + +## Audience +- Primary: first-time contributors/operators. +- Secondary: returning maintainers handling operational workflows. +- Language: English only. + +## Information Architecture +The README will follow this exact high-level structure: + +1. **Project Overview** + - Mission, what this repo orchestrates, and what it does not own. +2. **Repository Topology** + - Parent repo responsibilities. + - Submodule map (`program/*`) with one-line purpose per repo. +3. **Quick Start (10-Minute Path)** + - Minimal onboarding path to get a clean working environment. +4. **Full Environment Setup** + - Prerequisites, clone strategy, submodule sync/init, authentication notes. +5. **Operational Workflows (Day-2)** + - Running tracking pipeline, scraper-related flows, operational checks, safe cleanup. +6. **Verification Checkpoints** + - Command-level expected outputs and pass/fail indicators. +7. **Troubleshooting Playbooks** + - Common failures seen in this project (git/submodule, PR base, SSH/HTTPS, shell shim). +8. **Contribution & Change Workflow** + - Branching, test expectations, review sequencing, PR integration order. +9. **Safety, Recovery, and Cleanup** + - Idempotent recovery commands, non-destructive cleanup, rollback steps. +10. **References** + - Direct links to plan/spec files and key operational docs. + +## Content Standards +- Command-first: each actionable step includes copy-paste commands. +- Every major procedure includes: + - **Prerequisites** + - **Execution** + - **Validation** + - **Recovery / rollback (when relevant)** +- Distinguish clearly: + - Parent-repo commands vs submodule commands. + - One-time setup vs routine operations. +- Use concise but professional tone; avoid ambiguity and placeholders. + +## Critical Accuracy Requirements +- Must reflect the current submodule-based architecture in `program/*`. +- Must include explicit guardrails for common confusion points: + - “No commits between branches” in parent repo vs nested repos. + - Default branch/base branch mismatch. + - SSH push failures and HTTPS fallback. + - Worktree + submodule interactions. +- Must preserve legal/operational boundaries already established in project docs. + +## Risks and Mitigations +- Risk: README becomes too monolithic and hard to scan. + - Mitigation: strict sectioning, quick-start first, deep details lower in file. +- Risk: Commands become stale. + - Mitigation: centralized references and clearly labeled command intent. +- Risk: Users run commands in wrong repo. + - Mitigation: add path prompts and “Run from:” notes per section. + +## Acceptance Criteria +- A new user can clone, initialize submodules, and run baseline workflows without external clarification. +- A maintainer can diagnose common operational failures using troubleshooting sections. +- README provides clear map to advanced docs without duplicating all deep content. +- All command blocks are path-scoped and include validation checkpoints. + From 5a4c19713d0bfd6d3cd35cf6b275d14e91d2becd Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sun, 3 May 2026 19:51:17 +0300 Subject: [PATCH 12/33] docs(plan): add master README guidance implementation plan Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ...3-master-readme-guidance-implementation.md | 455 ++++++++++++++++++ 1 file changed, 455 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md diff --git a/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md b/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md new file mode 100644 index 0000000..e8dd89b --- /dev/null +++ b/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md @@ -0,0 +1,455 @@ +# Master README Guidance Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Rewrite the root README into a comprehensive, command-driven onboarding and day-2 operations guide for the ROS parent repo and its submodule architecture. + +**Architecture:** Keep one authoritative root README with a strict section hierarchy: overview, topology, quickstart, full setup, operations, troubleshooting, contribution flow, and references. Use command-first instructions with explicit path context and verification checkpoints. Avoid duplicating deep technical docs by linking to existing spec/plan artifacts where detail already exists. + +**Tech Stack:** Markdown, Git/GitHub CLI command recipes, shell command verification checkpoints. + +--- + +## File Structure Plan + +- Modify: `/mnt/data/ros/README.md` — replace current minimal content with the full professional guidance manual. +- Verify references only (no content changes expected): + - `/mnt/data/ros/docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md` + - `/mnt/data/ros/program/research-program-index/README.md` + - `/mnt/data/ros/program/benchmark-core/README.md` + - `/mnt/data/ros/.gitmodules` + +--- + +### Task 1: Replace README with approved architecture skeleton + +**Files:** +- Modify: `/mnt/data/ros/README.md` + +- [ ] **Step 1: Write the new top-level README structure** + +Replace `README.md` contents with this exact initial skeleton: + +```markdown +# ROS Program Workspace + +Professional operating manual for the ROS parent repository and its managed multi-repo research program. + +## 1. What This Repository Is + +This parent repository orchestrates the full program workspace, shared workflows, and submodule pointers for domain repositories under `program/`. + +It is the control plane for: +- repository topology +- shared workflows and guidance +- reproducible workspace bootstrap +- integration flow across subrepos + +It is **not** where all implementation code lives; implementation is distributed in submodules. + +## 2. Repository Topology + +### 2.1 Parent Repo Responsibilities +- root-level orchestration +- docs/specs/plans +- shared scripts and operational guidance +- submodule pinning for exact child-repo states + +### 2.2 Submodule Repositories (`program/`) +- `research-program-index`: orchestration roadmap, governance, release schema +- `benchmark-core`: benchmark contracts and baseline verification tests +- `localization-tracking`: localization and tracking domain work +- `uav-mpc-geometric-control`: UAV MPC and geometric control domain work +- `sensorless-estimation-suite`: sensorless estimation workflows +- `swarm-path-planning-bees`: swarm/path-planning workflows +- `ik-uncertainty-learning`: inverse-kinematics uncertainty workflows +- `digital-twin-pipeline`: digital twin integration pipeline +- `docs-multilingual-continuity`: documentation continuity assets +- `repro-packages`: reproducibility packaging artifacts + +## 3. Quick Start (10-Minute Path) + +## 4. Full Setup (First-Time Environment) + +## 5. Day-2 Operations + +## 6. Troubleshooting Playbooks + +## 7. Contribution Workflow + +## 8. Safety, Recovery, and Cleanup + +## 9. References +``` + +- [ ] **Step 2: Run markdown sanity check by visual scan** + +Run: + +```bash +cd /mnt/data/ros +sed -n '1,140p' README.md +``` + +Expected: All section headers `## 1` through `## 9` visible in order; no old duplicate `# ROS` headings remain. + +- [ ] **Step 3: Commit skeleton** + +```bash +cd /mnt/data/ros +git add README.md +git commit -m "docs: scaffold comprehensive root README structure" +``` + +--- + +### Task 2: Add command-driven onboarding and setup sections + +**Files:** +- Modify: `/mnt/data/ros/README.md` + +- [ ] **Step 1: Fill `## 3. Quick Start (10-Minute Path)`** + +Under section 3, add exactly: + +```markdown +## 3. Quick Start (10-Minute Path) + +Run from a clean terminal: + +```bash +git clone --recurse-submodules https://github.com/molhamfetnah/ROS.git +cd ROS +git submodule sync --recursive +git submodule update --init --recursive +``` + +Validation checkpoint: + +```bash +git submodule status +``` + +Expected: 10 `program/*` entries listed with commit SHAs. +``` + +- [ ] **Step 2: Fill `## 4. Full Setup (First-Time Environment)`** + +Under section 4, add: + +```markdown +## 4. Full Setup (First-Time Environment) + +### 4.1 Ensure parent repo is current + +```bash +cd /mnt/data/ros +git checkout main +git pull --ff-only +``` + +Expected: `Already up to date.` or fast-forward output. + +### 4.2 Initialize submodules + +```bash +git submodule sync --recursive +git submodule update --init --recursive +``` + +Expected: each `program/*` submodule checked out with no errors. + +### 4.3 Verify workspace health + +```bash +git status --short --branch +git submodule status +``` + +Expected: +- parent branch shown (normally `## main`) +- no unexpected dirty state +- submodule SHAs listed + +### 4.4 GitHub CLI auth (for push/PR operations) + +```bash +gh auth status || gh auth login +gh repo view molhamfetnah/ROS --json defaultBranchRef +``` + +Expected: authenticated account and default branch details returned. +``` + +- [ ] **Step 3: Validate sections render correctly** + +```bash +cd /mnt/data/ros +sed -n '1,260p' README.md +``` + +Expected: Setup sections include command blocks + expected outcomes after each block. + +- [ ] **Step 4: Commit onboarding/setup** + +```bash +cd /mnt/data/ros +git add README.md +git commit -m "docs: add quickstart and full setup procedures" +``` + +--- + +### Task 3: Add day-2 operations and troubleshooting playbooks + +**Files:** +- Modify: `/mnt/data/ros/README.md` + +- [ ] **Step 1: Fill `## 5. Day-2 Operations` with operational workflows** + +Add: + +```markdown +## 5. Day-2 Operations + +### 5.1 Sync workspace before work + +```bash +cd /mnt/data/ros +git checkout main +git pull --ff-only +git submodule sync --recursive +git submodule update --init --recursive +``` + +### 5.2 Worktree-based feature workflow + +```bash +cd /mnt/data/ros +git worktree add .worktrees/ -b +cd .worktrees/ +``` + +### 5.3 Tracking-system usage (parent repo only) + +After shim install, run: + +```bash +cd /mnt/data/ros +git status +ls -la .tracking +``` + +Expected: +- `.tracking/latest.json` +- `.tracking/history.ndjson` +- `.tracking/latest.txt` + +### 5.4 Submodule-safe operations + +For submodule-specific work, run commands inside target submodule: + +```bash +cd /mnt/data/ros/program/research-program-index +git status +``` + +Parent-tracking artifacts should not be created inside submodules. +``` + +- [ ] **Step 2: Fill `## 6. Troubleshooting Playbooks`** + +Add: + +```markdown +## 6. Troubleshooting Playbooks + +### Issue A: `No commits between ...` when creating PR in parent repo + +Cause: work happened inside submodules, not parent tracked files. + +Fix: +```bash +cd /mnt/data/ros +git status --short +git diff --submodule +``` + +If parent has no diff, create PR in the child repo instead. + +### Issue B: SSH push timeout (`github.com:22`) + +Fix: +```bash +gh config set git_protocol https +gh auth setup-git +git remote -v +``` + +Retry push after protocol switch. + +### Issue C: Wrong base branch/default branch mismatch + +Check: +```bash +gh repo view molhamfetnah/ROS --json defaultBranchRef +git branch -a +``` + +Set correct default branch if needed: +```bash +gh repo edit molhamfetnah/ROS --default-branch main +``` + +### Issue D: Submodule state drift + +Fix: +```bash +cd /mnt/data/ros +git submodule sync --recursive +git submodule update --init --recursive +git submodule status +``` +``` + +- [ ] **Step 3: Validate operational/troubleshooting sections** + +```bash +cd /mnt/data/ros +grep -n "^## 5\\|^## 6\\|^### Issue" README.md +``` + +Expected: section 5/6 headers present and issue playbooks listed. + +- [ ] **Step 4: Commit day-2 + troubleshooting** + +```bash +cd /mnt/data/ros +git add README.md +git commit -m "docs: add day-2 operations and troubleshooting playbooks" +``` + +--- + +### Task 4: Add contribution workflow, safety, and reference map + +**Files:** +- Modify: `/mnt/data/ros/README.md` + +- [ ] **Step 1: Fill `## 7. Contribution Workflow`** + +Add: + +```markdown +## 7. Contribution Workflow + +### 7.1 Branching model +- Parent repo: orchestration/docs/submodule-pointer changes. +- Child repo: domain implementation changes. + +### 7.2 PR sequencing +1. Merge child-repo PRs first. +2. Update/pin submodule pointers in parent. +3. Merge parent PR last. + +### 7.3 Pre-PR checks + +```bash +cd /mnt/data/ros +git status --short --branch +git submodule status +bash scripts/tests/test-track-git-status.sh +bash scripts/tests/test-git-tracking-shim.sh +``` + +Expected: clean or intentional diff only; test scripts pass. +``` + +- [ ] **Step 2: Fill `## 8. Safety, Recovery, and Cleanup`** + +Add: + +```markdown +## 8. Safety, Recovery, and Cleanup + +### 8.1 Safe cleanup + +```bash +cd /mnt/data/ros +git checkout main +git pull --ff-only +git fetch --prune +``` + +### 8.2 Remove finished worktree + +```bash +git worktree list +git worktree remove .worktrees/ +``` + +### 8.3 Submodule recovery + +```bash +git submodule sync --recursive +git submodule update --init --recursive +``` + +### 8.4 DO NOT use destructive reset without explicit intent +- Avoid `git reset --hard` unless you explicitly want to discard local work. +``` + +- [ ] **Step 3: Fill `## 9. References`** + +Add: + +```markdown +## 9. References + +- Design spec: `docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md` +- Tracking implementation plan: `docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md` +- Repo architecture spec: `docs/superpowers/specs/2026-04-30-repo-architecture-design.md` +- Program bootstrap plan: `docs/superpowers/plans/2026-04-30-multi-repo-program-bootstrap.md` +- Core subrepos: + - `program/research-program-index/README.md` + - `program/benchmark-core/README.md` +``` + +- [ ] **Step 4: Validate links and section completeness** + +```bash +cd /mnt/data/ros +for p in \ + docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md \ + docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md \ + docs/superpowers/specs/2026-04-30-repo-architecture-design.md \ + docs/superpowers/plans/2026-04-30-multi-repo-program-bootstrap.md \ + program/research-program-index/README.md \ + program/benchmark-core/README.md; do + test -f "$p" || { echo "missing: $p"; exit 1; } +done +echo "reference-check: PASS" +``` + +Expected: `reference-check: PASS`. + +- [ ] **Step 5: Commit final README rewrite** + +```bash +cd /mnt/data/ros +git add README.md +git commit -m "docs: publish comprehensive root README operations guide" +``` + +--- + +## Spec Coverage Check (self-review) + +1. **Single master README approach:** covered (Tasks 1–4 only modify root README). +2. **Onboarding + day-2 operations:** covered (Tasks 2 and 3). +3. **Command-driven with expected checkpoints:** covered throughout each task. +4. **Parent vs submodule boundaries:** covered in topology, operations, troubleshooting. +5. **Professional troubleshooting and contribution flow:** covered in Tasks 3 and 4. +6. **Reference map to deeper docs:** covered in Task 4 references section. +7. **No placeholders/TBDs:** all sections and command blocks explicitly defined. + From 88c2086cf34364fb37c20e4e887c5e148998c721 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sun, 3 May 2026 19:53:08 +0300 Subject: [PATCH 13/33] docs: scaffold comprehensive root README structure Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5598dbf..53a275a 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,49 @@ -# ROS -# ROS +# ROS Program Workspace + +Professional operating manual for the ROS parent repository and its managed multi-repo research program. + +## 1. What This Repository Is + +This parent repository orchestrates the full program workspace, shared workflows, and submodule pointers for domain repositories under `program/`. + +It is the control plane for: +- repository topology +- shared workflows and guidance +- reproducible workspace bootstrap +- integration flow across subrepos + +It is **not** where all implementation code lives; implementation is distributed in submodules. + +## 2. Repository Topology + +### 2.1 Parent Repo Responsibilities +- root-level orchestration +- docs/specs/plans +- shared scripts and operational guidance +- submodule pinning for exact child-repo states + +### 2.2 Submodule Repositories (`program/`) +- `research-program-index`: orchestration roadmap, governance, release schema +- `benchmark-core`: benchmark contracts and baseline verification tests +- `localization-tracking`: localization and tracking domain work +- `uav-mpc-geometric-control`: UAV MPC and geometric control domain work +- `sensorless-estimation-suite`: sensorless estimation workflows +- `swarm-path-planning-bees`: swarm/path-planning workflows +- `ik-uncertainty-learning`: inverse-kinematics uncertainty workflows +- `digital-twin-pipeline`: digital twin integration pipeline +- `docs-multilingual-continuity`: documentation continuity assets +- `repro-packages`: reproducibility packaging artifacts + +## 3. Quick Start (10-Minute Path) + +## 4. Full Setup (First-Time Environment) + +## 5. Day-2 Operations + +## 6. Troubleshooting Playbooks + +## 7. Contribution Workflow + +## 8. Safety, Recovery, and Cleanup + +## 9. References From 58cb48f1f5e2ad17778f3435de22eb6e1c30624a Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sun, 3 May 2026 19:56:28 +0300 Subject: [PATCH 14/33] docs: add quickstart and full setup procedures Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/README.md b/README.md index 53a275a..3b03f53 100644 --- a/README.md +++ b/README.md @@ -36,8 +36,65 @@ It is **not** where all implementation code lives; implementation is distributed ## 3. Quick Start (10-Minute Path) +Run from a clean terminal: + +```bash +git clone --recurse-submodules https://github.com/molhamfetnah/ROS.git +cd ROS +git submodule sync --recursive +git submodule update --init --recursive +``` + +Validation checkpoint: + +```bash +git submodule status +``` + +Expected: 10 `program/*` entries listed with commit SHAs. + ## 4. Full Setup (First-Time Environment) +### 4.1 Ensure parent repo is current + +```bash +cd /mnt/data/ros +git checkout main +git pull --ff-only +``` + +Expected: `Already up to date.` or fast-forward output. + +### 4.2 Initialize submodules + +```bash +git submodule sync --recursive +git submodule update --init --recursive +``` + +Expected: each `program/*` submodule checked out with no errors. + +### 4.3 Verify workspace health + +```bash +git status --short --branch +git submodule status +``` + +Expected: +- parent branch shown (normally `## main`) +- no unexpected dirty state +- submodule SHAs listed + +### 4.4 GitHub CLI auth (for push/PR operations) + +```bash +gh auth status || gh auth login +gh repo view molhamfetnah/ROS --json defaultBranchRef +``` + +Expected: authenticated account and default branch details returned. + ## 5. Day-2 Operations ## 6. Troubleshooting Playbooks From de05df679c501839d7d6398e9a9df36ee65135d9 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Sun, 3 May 2026 19:59:35 +0300 Subject: [PATCH 15/33] docs: make setup path instructions portable Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3b03f53..88fbca0 100644 --- a/README.md +++ b/README.md @@ -58,12 +58,16 @@ Expected: 10 `program/*` entries listed with commit SHAs. ### 4.1 Ensure parent repo is current ```bash -cd /mnt/data/ros +cd ROS +# or: cd +git rev-parse --show-toplevel git checkout main git pull --ff-only ``` -Expected: `Already up to date.` or fast-forward output. +Expected: +- `git rev-parse --show-toplevel` prints a path ending with `/ROS` +- `Already up to date.` or fast-forward output. ### 4.2 Initialize submodules From 7e4cb630f94a8f4e92c6cb584674585e5b27491f Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 10:39:33 +0300 Subject: [PATCH 16/33] docs: harden setup repo path validation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 88fbca0..ed33044 100644 --- a/README.md +++ b/README.md @@ -58,15 +58,15 @@ Expected: 10 `program/*` entries listed with commit SHAs. ### 4.1 Ensure parent repo is current ```bash -cd ROS -# or: cd +cd || exit 1 git rev-parse --show-toplevel +test "$(basename "$(git rev-parse --show-toplevel)")" = "ROS" || exit 1 git checkout main git pull --ff-only ``` Expected: -- `git rev-parse --show-toplevel` prints a path ending with `/ROS` +- `git rev-parse --show-toplevel` prints the absolute path to your clone root, and the repo identity check passes (`ROS`) - `Already up to date.` or fast-forward output. ### 4.2 Initialize submodules From e80e2248531d2d8b8e1752e73d2b5f5bb582054d Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 10:41:59 +0300 Subject: [PATCH 17/33] docs: enforce repo identity check in setup Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ed33044..3845479 100644 --- a/README.md +++ b/README.md @@ -60,13 +60,16 @@ Expected: 10 `program/*` entries listed with commit SHAs. ```bash cd || exit 1 git rev-parse --show-toplevel -test "$(basename "$(git rev-parse --show-toplevel)")" = "ROS" || exit 1 +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq 'github\.com[:/].+/ROS(\.git)?$' || { echo "Error: origin must point to the ROS repository." >&2; exit 1; } git checkout main git pull --ff-only ``` Expected: -- `git rev-parse --show-toplevel` prints the absolute path to your clone root, and the repo identity check passes (`ROS`) +- `git rev-parse --show-toplevel` prints the absolute path to your clone root. +- Worktree and `origin` identity checks pass before branch mutation commands run. - `Already up to date.` or fast-forward output. ### 4.2 Initialize submodules From 715c99e745db771e13a2e6a44310b339188b2682 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 10:44:36 +0300 Subject: [PATCH 18/33] docs: require exact ROS origin in setup guard Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3845479..7fc3e8e 100644 --- a/README.md +++ b/README.md @@ -62,14 +62,14 @@ cd || exit 1 git rev-parse --show-toplevel git rev-parse --is-inside-work-tree >/dev/null origin_url="$(git remote get-url origin 2>/dev/null || true)" -printf '%s\n' "$origin_url" | grep -Eq 'github\.com[:/].+/ROS(\.git)?$' || { echo "Error: origin must point to the ROS repository." >&2; exit 1; } +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } git checkout main git pull --ff-only ``` Expected: - `git rev-parse --show-toplevel` prints the absolute path to your clone root. -- Worktree and `origin` identity checks pass before branch mutation commands run. +- Worktree and exact canonical `origin` identity checks pass before branch mutation commands run. - `Already up to date.` or fast-forward output. ### 4.2 Initialize submodules From a5917b577b07b60e6d9c7f76131755389cec0820 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 10:48:27 +0300 Subject: [PATCH 19/33] docs: add day-2 operations and troubleshooting playbooks Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/README.md b/README.md index 7fc3e8e..e259a8a 100644 --- a/README.md +++ b/README.md @@ -104,8 +104,99 @@ Expected: authenticated account and default branch details returned. ## 5. Day-2 Operations +### 5.1 Sync workspace before work + +```bash +cd /mnt/data/ros +git checkout main +git pull --ff-only +git submodule sync --recursive +git submodule update --init --recursive +``` + +### 5.2 Worktree-based feature workflow + +```bash +cd /mnt/data/ros +git worktree add .worktrees/ -b +cd .worktrees/ +``` + +### 5.3 Tracking-system usage (parent repo only) + +After shim install, run: + +```bash +cd /mnt/data/ros +git status +ls -la .tracking +``` + +Expected: +- `.tracking/latest.json` +- `.tracking/history.ndjson` +- `.tracking/latest.txt` + +### 5.4 Submodule-safe operations + +For submodule-specific work, run commands inside target submodule: + +```bash +cd /mnt/data/ros/program/research-program-index +git status +``` + +Parent-tracking artifacts should not be created inside submodules. + ## 6. Troubleshooting Playbooks +### Issue A: `No commits between ...` when creating PR in parent repo + +Cause: work happened inside submodules, not parent tracked files. + +Fix: +```bash +cd /mnt/data/ros +git status --short +git diff --submodule +``` + +If parent has no diff, create PR in the child repo instead. + +### Issue B: SSH push timeout (`github.com:22`) + +Fix: +```bash +gh config set git_protocol https +gh auth setup-git +git remote -v +``` + +Retry push after protocol switch. + +### Issue C: Wrong base branch/default branch mismatch + +Check: +```bash +gh repo view molhamfetnah/ROS --json defaultBranchRef +git branch -a +``` + +Set correct default branch if needed: +```bash +gh repo edit molhamfetnah/ROS --default-branch main +``` + +### Issue D: Submodule state drift + +Fix: +```bash +cd /mnt/data/ros +git submodule sync --recursive +git submodule update --init --recursive +git submodule status +``` + ## 7. Contribution Workflow ## 8. Safety, Recovery, and Cleanup From a49e39475e8b21ef7792859dc98fb4bfc8bd2091 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 10:52:22 +0300 Subject: [PATCH 20/33] docs: harden operations and PR-base troubleshooting guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index e259a8a..9bb4b91 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,8 @@ Expected: authenticated account and default branch details returned. ### 5.1 Sync workspace before work ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel git checkout main git pull --ff-only git submodule sync --recursive @@ -117,7 +118,8 @@ git submodule update --init --recursive ### 5.2 Worktree-based feature workflow ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel git worktree add .worktrees/ -b cd .worktrees/ ``` @@ -127,7 +129,8 @@ cd .worktrees/ After shim install, run: ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel git status ls -la .tracking ``` @@ -142,7 +145,8 @@ Expected: For submodule-specific work, run commands inside target submodule: ```bash -cd /mnt/data/ros/program/research-program-index +cd /program/research-program-index || exit 1 +git rev-parse --show-toplevel git status ``` @@ -156,7 +160,8 @@ Cause: work happened inside submodules, not parent tracked files. Fix: ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel git status --short git diff --submodule ``` @@ -179,19 +184,25 @@ Retry push after protocol switch. Check: ```bash gh repo view molhamfetnah/ROS --json defaultBranchRef -git branch -a +gh pr view --json baseRefName,headRefName,url ``` -Set correct default branch if needed: +Create PR with explicit base (safe, PR-scoped): ```bash -gh repo edit molhamfetnah/ROS --default-branch main +gh pr create --base main +``` + +Retarget an existing PR base (does not change repository default branch): +```bash +gh pr edit --base main ``` ### Issue D: Submodule state drift Fix: ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel git submodule sync --recursive git submodule update --init --recursive git submodule status From 53c95ebfb7119543f0e758014f2481a3cfc8a5fb Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 10:55:34 +0300 Subject: [PATCH 21/33] docs: correct worktree and PR troubleshooting commands Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9bb4b91..d90d53a 100644 --- a/README.md +++ b/README.md @@ -120,7 +120,7 @@ git submodule update --init --recursive ```bash cd || exit 1 git rev-parse --show-toplevel -git worktree add .worktrees/ -b +git worktree add -b .worktrees/ cd .worktrees/ ``` @@ -183,18 +183,22 @@ Retry push after protocol switch. Check: ```bash +cd || exit 1 +git rev-parse --show-toplevel +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } gh repo view molhamfetnah/ROS --json defaultBranchRef -gh pr view --json baseRefName,headRefName,url +gh pr view --repo molhamfetnah/ROS --json baseRefName,headRefName,url ``` Create PR with explicit base (safe, PR-scoped): ```bash -gh pr create --base main +gh pr create --repo molhamfetnah/ROS --base main ``` Retarget an existing PR base (does not change repository default branch): ```bash -gh pr edit --base main +gh pr edit --repo molhamfetnah/ROS --base main ``` ### Issue D: Submodule state drift From 6239cd69a93a8622a5834fcb61b3f5b3a5d1e29f Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 10:57:34 +0300 Subject: [PATCH 22/33] docs: publish comprehensive root README operations guide Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/README.md b/README.md index d90d53a..2141240 100644 --- a/README.md +++ b/README.md @@ -214,6 +214,61 @@ git submodule status ## 7. Contribution Workflow +### 7.1 Branching model +- Parent repo: orchestration/docs/submodule-pointer changes. +- Child repo: domain implementation changes. + +### 7.2 PR sequencing +1. Merge child-repo PRs first. +2. Update/pin submodule pointers in parent. +3. Merge parent PR last. + +### 7.3 Pre-PR checks + +```bash +cd /mnt/data/ros +git status --short --branch +git submodule status +bash scripts/tests/test-track-git-status.sh +bash scripts/tests/test-git-tracking-shim.sh +``` + +Expected: clean or intentional diff only; test scripts pass. + ## 8. Safety, Recovery, and Cleanup +### 8.1 Safe cleanup + +```bash +cd /mnt/data/ros +git checkout main +git pull --ff-only +git fetch --prune +``` + +### 8.2 Remove finished worktree + +```bash +git worktree list +git worktree remove .worktrees/ +``` + +### 8.3 Submodule recovery + +```bash +git submodule sync --recursive +git submodule update --init --recursive +``` + +### 8.4 DO NOT use destructive reset without explicit intent +- Avoid `git reset --hard` unless you explicitly want to discard local work. + ## 9. References + +- Design spec: `docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md` +- Tracking implementation plan: `docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md` +- Repo architecture spec: `docs/superpowers/specs/2026-04-30-repo-architecture-design.md` +- Program bootstrap plan: `docs/superpowers/plans/2026-04-30-multi-repo-program-bootstrap.md` +- Core subrepos: + - `program/research-program-index/README.md` + - `program/benchmark-core/README.md` From e4c368d2c03cd1fe52f5f9a9cecfb52d01fbaf99 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 11:03:58 +0300 Subject: [PATCH 23/33] docs: align README reference links with existing plan files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- .../2026-05-03-master-readme-guidance-implementation.md | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2141240..ef9368a 100644 --- a/README.md +++ b/README.md @@ -268,7 +268,7 @@ git submodule update --init --recursive - Design spec: `docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md` - Tracking implementation plan: `docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md` - Repo architecture spec: `docs/superpowers/specs/2026-04-30-repo-architecture-design.md` -- Program bootstrap plan: `docs/superpowers/plans/2026-04-30-multi-repo-program-bootstrap.md` +- Master README implementation plan: `docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md` - Core subrepos: - `program/research-program-index/README.md` - `program/benchmark-core/README.md` diff --git a/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md b/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md index e8dd89b..a986689 100644 --- a/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md +++ b/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md @@ -409,7 +409,7 @@ Add: - Design spec: `docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md` - Tracking implementation plan: `docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md` - Repo architecture spec: `docs/superpowers/specs/2026-04-30-repo-architecture-design.md` -- Program bootstrap plan: `docs/superpowers/plans/2026-04-30-multi-repo-program-bootstrap.md` +- Master README implementation plan: `docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md` - Core subrepos: - `program/research-program-index/README.md` - `program/benchmark-core/README.md` @@ -423,7 +423,7 @@ for p in \ docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md \ docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md \ docs/superpowers/specs/2026-04-30-repo-architecture-design.md \ - docs/superpowers/plans/2026-04-30-multi-repo-program-bootstrap.md \ + docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md \ program/research-program-index/README.md \ program/benchmark-core/README.md; do test -f "$p" || { echo "missing: $p"; exit 1; } @@ -452,4 +452,3 @@ git commit -m "docs: publish comprehensive root README operations guide" 5. **Professional troubleshooting and contribution flow:** covered in Tasks 3 and 4. 6. **Reference map to deeper docs:** covered in Task 4 references section. 7. **No placeholders/TBDs:** all sections and command blocks explicitly defined. - From af86bfc522388a60347cfef4d2097211bc5466be Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 16:03:33 +0300 Subject: [PATCH 24/33] docs: clarify worktree context in pre-pr and cleanup Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ef9368a..0adaf2f 100644 --- a/README.md +++ b/README.md @@ -225,22 +225,37 @@ git submodule status ### 7.3 Pre-PR checks +Run these checks from the feature worktree that contains your PR changes (not the parent `main` checkout): + ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel +git branch --show-current git status --short --branch git submodule status bash scripts/tests/test-track-git-status.sh bash scripts/tests/test-git-tracking-shim.sh ``` +Use the parent checkout only for final parent-repo updates (submodule pointers/docs) before opening the parent PR: + +```bash +cd || exit 1 +git rev-parse --show-toplevel +git branch --show-current +``` + Expected: clean or intentional diff only; test scripts pass. ## 8. Safety, Recovery, and Cleanup ### 8.1 Safe cleanup +Run cleanup/sync commands from the parent `main` checkout, not from an active feature worktree: + ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel git checkout main git pull --ff-only git fetch --prune From 7506525cdc82855719428a7f8a131d007bd26e59 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 16:08:07 +0300 Subject: [PATCH 25/33] docs: enforce feature-branch context for parent updates Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 0adaf2f..c682718 100644 --- a/README.md +++ b/README.md @@ -230,21 +230,29 @@ Run these checks from the feature worktree that contains your PR changes (not th ```bash cd || exit 1 git rev-parse --show-toplevel -git branch --show-current +FEATURE_BRANCH= +CURRENT_BRANCH="$(git branch --show-current)" +test "$CURRENT_BRANCH" != "main" +test "$CURRENT_BRANCH" = "$FEATURE_BRANCH" git status --short --branch git submodule status bash scripts/tests/test-track-git-status.sh bash scripts/tests/test-git-tracking-shim.sh ``` -Use the parent checkout only for final parent-repo updates (submodule pointers/docs) before opening the parent PR: +Perform final parent-repo updates (submodule pointers/docs) in this same feature worktree branch only before opening the parent PR: ```bash -cd || exit 1 +cd || exit 1 git rev-parse --show-toplevel -git branch --show-current +FEATURE_BRANCH= +CURRENT_BRANCH="$(git branch --show-current)" +test "$CURRENT_BRANCH" != "main" +test "$CURRENT_BRANCH" = "$FEATURE_BRANCH" ``` +Reserve the parent `main` checkout for sync/cleanup commands only (see section 8.1). + Expected: clean or intentional diff only; test scripts pass. ## 8. Safety, Recovery, and Cleanup From e5a09ddb7938158b39cb1f6c7f3da8f4d2f28659 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 16:14:29 +0300 Subject: [PATCH 26/33] docs: scope submodule status checks to program repos Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c682718..dc8cbd7 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ git submodule update --init --recursive Validation checkpoint: ```bash -git submodule status +git submodule status -- program/* ``` Expected: 10 `program/*` entries listed with commit SHAs. @@ -85,13 +85,13 @@ Expected: each `program/*` submodule checked out with no errors. ```bash git status --short --branch -git submodule status +git submodule status -- program/* ``` Expected: - parent branch shown (normally `## main`) - no unexpected dirty state -- submodule SHAs listed +- 10 `program/*` submodule SHAs listed ### 4.4 GitHub CLI auth (for push/PR operations) @@ -209,7 +209,7 @@ cd || exit 1 git rev-parse --show-toplevel git submodule sync --recursive git submodule update --init --recursive -git submodule status +git submodule status -- program/* ``` ## 7. Contribution Workflow @@ -235,7 +235,7 @@ CURRENT_BRANCH="$(git branch --show-current)" test "$CURRENT_BRANCH" != "main" test "$CURRENT_BRANCH" = "$FEATURE_BRANCH" git status --short --branch -git submodule status +git submodule status -- program/* bash scripts/tests/test-track-git-status.sh bash scripts/tests/test-git-tracking-shim.sh ``` From 734593cb0d16b8b2f1983d618aca97bb118b4e46 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 16:20:14 +0300 Subject: [PATCH 27/33] docs: align README plan with final command safety rules Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 15 +++ ...3-master-readme-guidance-implementation.md | 93 ++++++++++++++----- 2 files changed, 87 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index dc8cbd7..857dacc 100644 --- a/README.md +++ b/README.md @@ -109,6 +109,9 @@ Expected: authenticated account and default branch details returned. ```bash cd || exit 1 git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } git checkout main git pull --ff-only git submodule sync --recursive @@ -120,6 +123,9 @@ git submodule update --init --recursive ```bash cd || exit 1 git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } git worktree add -b .worktrees/ cd .worktrees/ ``` @@ -230,6 +236,9 @@ Run these checks from the feature worktree that contains your PR changes (not th ```bash cd || exit 1 git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } FEATURE_BRANCH= CURRENT_BRANCH="$(git branch --show-current)" test "$CURRENT_BRANCH" != "main" @@ -245,6 +254,9 @@ Perform final parent-repo updates (submodule pointers/docs) in this same feature ```bash cd || exit 1 git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } FEATURE_BRANCH= CURRENT_BRANCH="$(git branch --show-current)" test "$CURRENT_BRANCH" != "main" @@ -264,6 +276,9 @@ Run cleanup/sync commands from the parent `main` checkout, not from an active fe ```bash cd || exit 1 git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } git checkout main git pull --ff-only git fetch --prune diff --git a/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md b/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md index a986689..c28f04b 100644 --- a/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md +++ b/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md @@ -203,7 +203,7 @@ git commit -m "docs: add quickstart and full setup procedures" ### Task 3: Add day-2 operations and troubleshooting playbooks **Files:** -- Modify: `/mnt/data/ros/README.md` +- Modify: `README.md` (repository root) - [ ] **Step 1: Fill `## 5. Day-2 Operations` with operational workflows** @@ -215,7 +215,11 @@ Add: ### 5.1 Sync workspace before work ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } git checkout main git pull --ff-only git submodule sync --recursive @@ -225,8 +229,12 @@ git submodule update --init --recursive ### 5.2 Worktree-based feature workflow ```bash -cd /mnt/data/ros -git worktree add .worktrees/ -b +cd || exit 1 +git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } +git worktree add -b .worktrees/ cd .worktrees/ ``` @@ -235,7 +243,8 @@ cd .worktrees/ After shim install, run: ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel git status ls -la .tracking ``` @@ -250,7 +259,8 @@ Expected: For submodule-specific work, run commands inside target submodule: ```bash -cd /mnt/data/ros/program/research-program-index +cd /program/research-program-index || exit 1 +git rev-parse --show-toplevel git status ``` @@ -270,7 +280,8 @@ Cause: work happened inside submodules, not parent tracked files. Fix: ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel git status --short git diff --submodule ``` @@ -292,39 +303,51 @@ Retry push after protocol switch. Check: ```bash +cd || exit 1 +git rev-parse --show-toplevel +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } gh repo view molhamfetnah/ROS --json defaultBranchRef -git branch -a +gh pr view --repo molhamfetnah/ROS --json baseRefName,headRefName,url +``` + +Create PR with explicit base (safe, PR-scoped): +```bash +gh pr create --repo molhamfetnah/ROS --base main ``` -Set correct default branch if needed: +Retarget an existing PR base (does not change repository default branch): ```bash -gh repo edit molhamfetnah/ROS --default-branch main +gh pr edit --repo molhamfetnah/ROS --base main ``` ### Issue D: Submodule state drift Fix: ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel git submodule sync --recursive git submodule update --init --recursive -git submodule status +git submodule status -- program/* ``` ``` - [ ] **Step 3: Validate operational/troubleshooting sections** ```bash -cd /mnt/data/ros +cd || exit 1 grep -n "^## 5\\|^## 6\\|^### Issue" README.md +grep -n "git submodule status -- program/\\*" README.md +! grep -n "gh repo edit .*--default-branch" README.md ``` -Expected: section 5/6 headers present and issue playbooks listed. +Expected: section 5/6 headers present, scoped submodule status checks present, and no default-branch mutation command. - [ ] **Step 4: Commit day-2 + troubleshooting** ```bash -cd /mnt/data/ros +cd || exit 1 git add README.md git commit -m "docs: add day-2 operations and troubleshooting playbooks" ``` @@ -334,7 +357,7 @@ git commit -m "docs: add day-2 operations and troubleshooting playbooks" ### Task 4: Add contribution workflow, safety, and reference map **Files:** -- Modify: `/mnt/data/ros/README.md` +- Modify: `README.md` (repository root) - [ ] **Step 1: Fill `## 7. Contribution Workflow`** @@ -355,13 +378,37 @@ Add: ### 7.3 Pre-PR checks ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } +FEATURE_BRANCH= +CURRENT_BRANCH="$(git branch --show-current)" +test "$CURRENT_BRANCH" != "main" +test "$CURRENT_BRANCH" = "$FEATURE_BRANCH" git status --short --branch -git submodule status +git submodule status -- program/* bash scripts/tests/test-track-git-status.sh bash scripts/tests/test-git-tracking-shim.sh ``` +Perform final parent-repo updates (submodule pointers/docs) in this same feature worktree branch only before opening the parent PR: + +```bash +cd || exit 1 +git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } +FEATURE_BRANCH= +CURRENT_BRANCH="$(git branch --show-current)" +test "$CURRENT_BRANCH" != "main" +test "$CURRENT_BRANCH" = "$FEATURE_BRANCH" +``` + +Reserve the parent `main` checkout for sync/cleanup commands only (see section 8.1). + Expected: clean or intentional diff only; test scripts pass. ``` @@ -375,7 +422,11 @@ Add: ### 8.1 Safe cleanup ```bash -cd /mnt/data/ros +cd || exit 1 +git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } git checkout main git pull --ff-only git fetch --prune @@ -418,7 +469,7 @@ Add: - [ ] **Step 4: Validate links and section completeness** ```bash -cd /mnt/data/ros +cd || exit 1 for p in \ docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md \ docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md \ @@ -436,7 +487,7 @@ Expected: `reference-check: PASS`. - [ ] **Step 5: Commit final README rewrite** ```bash -cd /mnt/data/ros +cd || exit 1 git add README.md git commit -m "docs: publish comprehensive root README operations guide" ``` From 625f8d5113408e21e6ddd7e5401fcd4836692bf7 Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 16:25:45 +0300 Subject: [PATCH 28/33] docs: finalize worktree and cleanup safety guards Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 12 ++++++++++++ ...26-05-03-master-readme-guidance-implementation.md | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/README.md b/README.md index 857dacc..8c15fb4 100644 --- a/README.md +++ b/README.md @@ -126,6 +126,8 @@ git rev-parse --show-toplevel git rev-parse --is-inside-work-tree >/dev/null origin_url="$(git remote get-url origin 2>/dev/null || true)" printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } +git checkout main +git pull --ff-only git worktree add -b .worktrees/ cd .worktrees/ ``` @@ -287,6 +289,11 @@ git fetch --prune ### 8.2 Remove finished worktree ```bash +cd || exit 1 +git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } git worktree list git worktree remove .worktrees/ ``` @@ -294,6 +301,11 @@ git worktree remove .worktrees/ ### 8.3 Submodule recovery ```bash +cd || exit 1 +git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } git submodule sync --recursive git submodule update --init --recursive ``` diff --git a/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md b/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md index c28f04b..41df0a6 100644 --- a/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md +++ b/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md @@ -234,6 +234,8 @@ git rev-parse --show-toplevel git rev-parse --is-inside-work-tree >/dev/null origin_url="$(git remote get-url origin 2>/dev/null || true)" printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } +git checkout main +git pull --ff-only git worktree add -b .worktrees/ cd .worktrees/ ``` @@ -435,6 +437,11 @@ git fetch --prune ### 8.2 Remove finished worktree ```bash +cd || exit 1 +git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } git worktree list git worktree remove .worktrees/ ``` @@ -442,6 +449,11 @@ git worktree remove .worktrees/ ### 8.3 Submodule recovery ```bash +cd || exit 1 +git rev-parse --show-toplevel +git rev-parse --is-inside-work-tree >/dev/null +origin_url="$(git remote get-url origin 2>/dev/null || true)" +printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } git submodule sync --recursive git submodule update --init --recursive ``` From eed0f8927d0848df84f6e9c712ac11a9750eb5ac Mon Sep 17 00:00:00 2001 From: Mulham Fetna Date: Mon, 4 May 2026 16:29:39 +0300 Subject: [PATCH 29/33] docs: enforce fail-fast main base before worktree add Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 4 ++-- .../plans/2026-05-03-master-readme-guidance-implementation.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8c15fb4..5d2a354 100644 --- a/README.md +++ b/README.md @@ -126,8 +126,8 @@ git rev-parse --show-toplevel git rev-parse --is-inside-work-tree >/dev/null origin_url="$(git remote get-url origin 2>/dev/null || true)" printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } -git checkout main -git pull --ff-only +git checkout main || exit 1 +git pull --ff-only || exit 1 git worktree add -b .worktrees/ cd .worktrees/ ``` diff --git a/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md b/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md index 41df0a6..318131a 100644 --- a/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md +++ b/docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md @@ -234,8 +234,8 @@ git rev-parse --show-toplevel git rev-parse --is-inside-work-tree >/dev/null origin_url="$(git remote get-url origin 2>/dev/null || true)" printf '%s\n' "$origin_url" | grep -Eq '^(git@github\.com:molhamfetnah/ROS(\.git)?|https://github\.com/molhamfetnah/ROS(\.git)?)$' || { echo "Error: origin must be molhamfetnah/ROS (SSH or HTTPS)." >&2; exit 1; } -git checkout main -git pull --ff-only +git checkout main || exit 1 +git pull --ff-only || exit 1 git worktree add -b .worktrees/ cd .worktrees/ ``` From 057f1a5ae64cea49821930d7bb79cf7d9d3728b3 Mon Sep 17 00:00:00 2001 From: Mulham Fetna <76975497+molhamfetnah@users.noreply.github.com> Date: Mon, 4 May 2026 17:20:42 +0300 Subject: [PATCH 30/33] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5d2a354..046f35e 100644 --- a/README.md +++ b/README.md @@ -134,11 +134,13 @@ cd .worktrees/ ### 5.3 Tracking-system usage (parent repo only) -After shim install, run: +Install the git tracking shim first, then start a new shell (or source your shell rc file) so the shim is active, and run: ```bash cd || exit 1 git rev-parse --show-toplevel +scripts/install-git-tracking-shim.sh +# Start a new shell, or source your shell rc file before continuing. git status ls -la .tracking ``` From d0ac0cce0ff6aa82b91d60a20e1b91644dbb9823 Mon Sep 17 00:00:00 2001 From: Mulham Fetna <76975497+molhamfetnah@users.noreply.github.com> Date: Mon, 4 May 2026 17:20:58 +0300 Subject: [PATCH 31/33] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- scripts/track-git-status.sh | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/scripts/track-git-status.sh b/scripts/track-git-status.sh index 1e0e4ae..d77e46f 100755 --- a/scripts/track-git-status.sh +++ b/scripts/track-git-status.sh @@ -5,7 +5,12 @@ REPO_ROOT="" BRANCH="" PORCELAIN_FILE="" TRACKING_DIR="" -MAX_BYTES="${TRACKING_MAX_BYTES:-10485760}" +TRACKING_MAX_BYTES_RAW="${TRACKING_MAX_BYTES:-}" +if [[ "$TRACKING_MAX_BYTES_RAW" =~ ^[0-9]+$ ]]; then + MAX_BYTES="$TRACKING_MAX_BYTES_RAW" +else + MAX_BYTES="10485760" +fi while [[ $# -gt 0 ]]; do case "$1" in From 6381648234746ac0106c62a1e5fd077c131bc7e5 Mon Sep 17 00:00:00 2001 From: Mulham Fetna <76975497+molhamfetnah@users.noreply.github.com> Date: Mon, 4 May 2026 17:21:13 +0300 Subject: [PATCH 32/33] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- scripts/install-git-tracking-shim.sh | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/scripts/install-git-tracking-shim.sh b/scripts/install-git-tracking-shim.sh index ce9fa06..1fc57d9 100755 --- a/scripts/install-git-tracking-shim.sh +++ b/scripts/install-git-tracking-shim.sh @@ -4,7 +4,9 @@ set -euo pipefail BASHRC="${HOME}/.bashrc" MARK_START="# >>> ros git tracking shim >>>" MARK_END="# <<< ros git tracking shim <<<" -SNIPPET="/mnt/data/ros/session/docs/snippets/git-tracking-shim.bash" +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +SNIPPET="${REPO_ROOT}/docs/snippets/git-tracking-shim.bash" SOURCE_LINE="[ -f \"$SNIPPET\" ] && source \"$SNIPPET\"" touch "$BASHRC" From 4b1be1f66407bdf8bda5824e1005013fb628eaa2 Mon Sep 17 00:00:00 2001 From: Mulham Fetna <76975497+molhamfetnah@users.noreply.github.com> Date: Mon, 4 May 2026 17:21:40 +0300 Subject: [PATCH 33/33] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- scripts/track-git-status.sh | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/scripts/track-git-status.sh b/scripts/track-git-status.sh index d77e46f..c372c4d 100755 --- a/scripts/track-git-status.sh +++ b/scripts/track-git-status.sh @@ -42,6 +42,13 @@ if [[ -z "$REPO_ROOT" || -z "$BRANCH" || -z "$PORCELAIN_FILE" || -z "$TRACKING_D exit 2 fi +for required_cmd in jq flock; do + if ! command -v "$required_cmd" >/dev/null 2>&1; then + echo "Missing required command: $required_cmd. Please install '$required_cmd' and retry." >&2 + exit 2 + fi +done + mkdir -p "$TRACKING_DIR" LATEST_JSON="$TRACKING_DIR/latest.json" HISTORY="$TRACKING_DIR/history.ndjson"