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)

Run from a clean terminal:

git clone --recurse-submodules https://github.com/molhamfetnah/ROS.git
cd ROS
git submodule sync --recursive
git submodule update --init --recursive

Validation checkpoint:

git submodule status -- program/*

Expected: 10 program/* entries listed with commit SHAs.

4. Full Setup (First-Time Environment)

4.1 Ensure parent repo is current

cd <path-to-your-ROS-clone> || 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

Expected:

git rev-parse --show-toplevel prints the absolute path to your clone root.
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

git submodule sync --recursive
git submodule update --init --recursive

Expected: each program/* submodule checked out with no errors.

4.3 Verify workspace health

git status --short --branch
git submodule status -- program/*

Expected:

parent branch shown (normally ## main)
no unexpected dirty state
10 program/* submodule SHAs listed

4.4 GitHub CLI auth (for push/PR operations)

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

5.1 Sync workspace before work

cd <path-to-your-ROS-clone> || 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
git submodule update --init --recursive

5.2 Worktree-based feature workflow

cd <path-to-your-ROS-clone> || 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 || exit 1
git pull --ff-only || exit 1
git worktree add -b <feature-branch> .worktrees/<feature-branch>
cd .worktrees/<feature-branch>

5.3 Tracking-system usage (parent repo only)

Install the git tracking shim first, then start a new shell (or source your shell rc file) so the shim is active, and run:

cd <path-to-your-ROS-clone> || 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

Expected:

.tracking/latest.json
.tracking/history.ndjson
.tracking/latest.txt

5.4 Submodule-safe operations

For submodule-specific work, run commands inside target submodule:

cd <path-to-your-ROS-clone>/program/research-program-index || exit 1
git rev-parse --show-toplevel
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:

cd <path-to-your-ROS-clone> || exit 1
git rev-parse --show-toplevel
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:

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:

cd <path-to-your-ROS-clone> || 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 <pr-number> --repo molhamfetnah/ROS --json baseRefName,headRefName,url

Create PR with explicit base (safe, PR-scoped):

gh pr create --repo molhamfetnah/ROS --base main

Retarget an existing PR base (does not change repository default branch):

gh pr edit <pr-number> --repo molhamfetnah/ROS --base main

Issue D: Submodule state drift

Fix:

cd <path-to-your-ROS-clone> || exit 1
git rev-parse --show-toplevel
git submodule sync --recursive
git submodule update --init --recursive
git submodule status -- program/*

7. Contribution Workflow

7.1 Branching model

Parent repo: orchestration/docs/submodule-pointer changes.
Child repo: domain implementation changes.

7.2 PR sequencing

Merge child-repo PRs first.
Update/pin submodule pointers in parent.
Merge parent PR last.

7.3 Pre-PR checks

Run these checks from the feature worktree that contains your PR changes (not the parent main checkout):

cd <path-to-your-feature-worktree> || 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=<your-feature-branch>
CURRENT_BRANCH="$(git branch --show-current)"
test "$CURRENT_BRANCH" != "main"
test "$CURRENT_BRANCH" = "$FEATURE_BRANCH"
git status --short --branch
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:

cd <path-to-your-feature-worktree> || 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=<your-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

8.1 Safe cleanup

Run cleanup/sync commands from the parent main checkout, not from an active feature worktree:

cd <path-to-your-ROS-clone> || 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

8.2 Remove finished worktree

cd <path-to-your-ROS-clone> || 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/<feature-branch>

8.3 Submodule recovery

cd <path-to-your-ROS-clone> || 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

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
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

10. Paper Submissions

#	Project	Journal	Manuscript ID	Status
1	Swarm (Bees Algorithm)	Applied Soft Computing	ASOC-D-26-06746	Received
2	IK Ensemble	IEEE RA-L	26-2479	Received
3	UAV Distributed MPC	Robotics and Autonomous Systems	ROBOT-D-26-01147	Received

Tracking

Applied Soft Computing: https://www.editorialmanager.com/ASOC
IEEE RA-L: https://ras.papercept.net/journals/ral
Robotics and Autonomous Systems: https://www.editorialmanager.com/ROBOT/

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
docs		docs
program		program
scripts		scripts
session		session
workspace		workspace
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
ARXIV_ACTION_PLAN.md		ARXIV_ACTION_PLAN.md
BABY_STEPS_ACTION_PLAN.md		BABY_STEPS_ACTION_PLAN.md
Dockerfile		Dockerfile
PAPER_SUBMISSION_LINKS.md		PAPER_SUBMISSION_LINKS.md
README.md		README.md
docker-compose.yml		docker-compose.yml
protonvpn-stable-release_1.0.8_all.deb		protonvpn-stable-release_1.0.8_all.deb
run.sh		run.sh
session-ses_206f.md		session-ses_206f.md

Folders and files

Latest commit

History

Repository files navigation

ROS Program Workspace

1. What This Repository Is

2. Repository Topology

2.1 Parent Repo Responsibilities

2.2 Submodule Repositories (program/)

3. Quick Start (10-Minute Path)

4. Full Setup (First-Time Environment)

4.1 Ensure parent repo is current

4.2 Initialize submodules

4.3 Verify workspace health

4.4 GitHub CLI auth (for push/PR operations)

5. Day-2 Operations

5.1 Sync workspace before work

5.2 Worktree-based feature workflow

5.3 Tracking-system usage (parent repo only)

5.4 Submodule-safe operations

6. Troubleshooting Playbooks

Issue A: No commits between ... when creating PR in parent repo

Issue B: SSH push timeout (github.com:22)

Issue C: Wrong base branch/default branch mismatch

Issue D: Submodule state drift

7. Contribution Workflow

7.1 Branching model

7.2 PR sequencing

7.3 Pre-PR checks

8. Safety, Recovery, and Cleanup

8.1 Safe cleanup

8.2 Remove finished worktree

8.3 Submodule recovery

8.4 DO NOT use destructive reset without explicit intent

9. References

10. Paper Submissions

Tracking

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

2.2 Submodule Repositories (`program/`)

Issue A: `No commits between ...` when creating PR in parent repo

Issue B: SSH push timeout (`github.com:22`)

Packages