From e2ad336039a045b80a34eccf96d08ae353c8e1c9 Mon Sep 17 00:00:00 2001 From: Bagas Purwa Sentika Date: Sun, 14 Jun 2026 21:57:33 +0800 Subject: [PATCH] docs(06): capture phase context --- .../06-default-repos-ssh-mount/06-CONTEXT.md | 119 ++++++++++++++++++ .../06-DISCUSSION-LOG.md | 81 ++++++++++++ 2 files changed, 200 insertions(+) create mode 100644 .planning/phases/06-default-repos-ssh-mount/06-CONTEXT.md create mode 100644 .planning/phases/06-default-repos-ssh-mount/06-DISCUSSION-LOG.md diff --git a/.planning/phases/06-default-repos-ssh-mount/06-CONTEXT.md b/.planning/phases/06-default-repos-ssh-mount/06-CONTEXT.md new file mode 100644 index 0000000..e586cbb --- /dev/null +++ b/.planning/phases/06-default-repos-ssh-mount/06-CONTEXT.md @@ -0,0 +1,119 @@ +# Phase 6: Default Repos & SSH Mount - Context + +**Gathered:** 2026-06-14 +**Status:** Ready for planning + + +## Phase Boundary + +Enable automatic availability of DEFAULT_REPOS in every new Hermes session and provide on-demand repo cloning capability. Repos are mounted directly from host filesystem (not cloned inside Docker) to preserve git worktrees and avoid redundant clones. + +**In scope:** SSH key mounting for git auth, repo volume mounts for 3 default repos, shell init script for session workspace setup, DEFAULT_REPOS configurability, on-demand cloning for additional repos + +**Out of scope:** Hindsight memory integration (Phase 5 already done), session lifecycle skill (Phase 7), cron reporting (Phase 8), migration of existing session data + + + +## Implementation Decisions + +### Git Auth Strategy +- **D-01:** Mount specific SSH keys read-only into Docker — `~/.ssh/id_ed25519razer` and `~/.ssh/id_rsa` plus `~/.ssh/config` + - Config: Add to `terminal.docker_volumes` in `~/.hermes/config.yaml` + - `~/.ssh/id_ed25519razer:/root/.ssh/id_ed25519razer:ro` + - `~/.ssh/id_rsa:/root/.ssh/id_rsa:ro` + - `~/.ssh/config:/root/.ssh/config:ro` + - The existing `~/.ssh/config` already maps `bitbucket.org` → `id_ed25519razer` + +### Repo Workspace Mounts +- **D-02:** Mount repo directories directly from host filesystem — repos live at `~/Razer/` and are mounted into Docker as host-mounted volumes + - Config: Add to `terminal.docker_volumes`: + - `~/Razer/rai-ops:/workspace/rai-ops:rw` + - `~/Razer/rai-deployment:/workspace/rai-deployment:rw` + - `~/Razer/rai-devtools:/workspace/rai-devtools:rw` + - This preserves existing git worktrees, branches, and avoids re-cloning + - Container has read-write access for git operations + +### Session Init Script +- **D-03:** Create `session-init.sh` in `~/.hermes/scripts/` (already mounted to `/usr/local/bin:ro`). Script checks that DEFAULT_REPOS are mounted at expected paths and logs status + - Config: Add to `terminal.shell_init_files`: `["/usr/local/bin/session-init.sh"]` + - Behavior: check each repo in DEFAULT_REPOS exists at `/workspace/`, log status, skip if absent (no blocking) + +### DEFAULT_REPOS Configurability +- **D-04:** `DEFAULT_REPOS` defined as an env var in `~/.hermes/.env`: + - `DEFAULT_REPOS=rai-ops,rai-deployment,rai-devtools` + - Forwarded into Docker via `docker_forward_env` + - The session init script reads this env var to validate mounts + - User can add/remove repos by editing .env + adding/removing volume mounts + +### On-Demand Repo Cloning (REPO-02) +- **D-05:** Agent clones additional repos into `/workspace/` using `git clone` inside Docker. SSH keys are mounted so auth works for any Bitbucket repo the user has access to + - Clones are ephemeral (lost on container restart) — suitable for temporary work + - Agent uses `git clone git@bitbucket.org:razersw/.git` + - No dedicated skill needed — git is available in the Docker image + +### the agent's Discretion +- **Init script error handling**: The script should exit gracefully if a repo is missing (non-blocking — session should still start) +- **On-demand clone destination**: Default to `/workspace/` unless user specifies otherwise + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Existing Hermes Configuration +- `~/.hermes/config.yaml` §`terminal.docker_volumes` — Current volume mounts (SSO cache, scripts) — the planner must append to this list +- `~/.hermes/config.yaml` §`terminal.shell_init_files` — Currently empty, needs `session-init.sh` +- `~/.hermes/config.yaml` §`terminal.docker_forward_env` — Currently forwards JIRA_EMAIL and JIRA_API_TOKEN +- `~/.hermes/scripts/` — Existing scripts directory (ngn-jira, ngn-confluence, ngn-bitbucket) — session-init.sh goes here +- `~/.hermes/.env` — Existing env vars (OPENROUTER_API_KEY, TELEGRAM_BOT_TOKEN, JIRA_API_TOKEN, etc.) + +### SSH Configuration +- `~/.ssh/config` — Maps bitbucket.org → `id_ed25519razer` +- `~/.ssh/id_ed25519razer` — Razer-specific SSH key +- `~/.ssh/id_rsa` — RSA key + +### Project Documents +- `.planning/REQUIREMENTS.md` §REPO-01, REPO-02 — Requirement definitions +- `.planning/ROADMAP.md` §Phase 6 — Phase goal and success criteria +- `.planning/research/SUMMARY.md` §Phase 2 — Research on repo mounting vs cloning, credential strategies +- `.planning/research/PITFALLS.md` — Git clone failures in Docker, SSH credential exposure risks + + + +## Existing Code Insights + +### Reusable Assets +- **`~/.hermes/scripts/` mount**: Already mounted to `/usr/local/bin:ro` — new `session-init.sh` goes here automatically +- **Docker volumes pattern**: Existing mount entries in config.yaml show the pattern (`host:container:mode`) + +### Established Patterns +- **Read-only sensitive files**: `.aws/config` mounted `:ro` — SSH keys follow the same pattern for security +- **Scripts mounted to /usr/local/bin**: `ngn-*` scripts already use this pattern — session-init.sh follows it + +### Integration Points +- `~/.hermes/config.yaml` §`terminal.docker_volumes` — Append SSH key + repo mounts +- `~/.hermes/config.yaml` §`terminal.shell_init_files` — Set to `["/usr/local/bin/session-init.sh"]` +- `~/.hermes/config.yaml` §`terminal.docker_forward_env` — Append `DEFAULT_REPOS` +- `~/.hermes/.env` — Add `DEFAULT_REPOS=rai-ops,rai-deployment,rai-devtools` +- `~/.hermes/scripts/session-init.sh` — New file (create) + + + +## Specific Ideas + +- Mount repos read-write (`:rw`) so git operations inside container (branch, commit, push) work seamlessly — this is the core advantage over cloning +- The session-init.sh should be lightweight: just verify mounts exist and log status. Do NOT attempt git operations — the repos are already on disk with active worktrees + + + +## Deferred Ideas + +- Auto-register repos as git worktrees via Hermes' `worktree: true` config — already handled by the host-side git setup +- Per-repo deploy keys instead of personal SSH key — future security hardening + + +--- + +*Phase: 6-Default Repos & SSH Mount* +*Context gathered: 2026-06-14* diff --git a/.planning/phases/06-default-repos-ssh-mount/06-DISCUSSION-LOG.md b/.planning/phases/06-default-repos-ssh-mount/06-DISCUSSION-LOG.md new file mode 100644 index 0000000..fb4b5ef --- /dev/null +++ b/.planning/phases/06-default-repos-ssh-mount/06-DISCUSSION-LOG.md @@ -0,0 +1,81 @@ +# Phase 6: Default Repos & SSH Mount - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-06-14 +**Phase:** 6-Default Repos & SSH Mount +**Areas discussed:** Git auth strategy, Workspace path, Init script, Default repos list, Configurability + +--- + +## Git Auth Strategy + +| Option | Description | Selected | +|--------|-------------|----------| +| Mount full ~/.ssh:ro | Simple, exposes all keys including personal ones | | +| Mount specific key files | More surgical — only the keys needed for bitbucket | ✓ | +| HTTPS + App Password | No SSH in container, env var based | | + +**User's choice:** Mount specific keys — `id_ed25519razer` and `id_rsa` plus `~/.ssh/config` +**Notes:** The config already maps bitbucket.org → `id_ed25519razer`. Keys mounted read-only. + +--- + +## Workspace Path + +| Option | Description | Selected | +|--------|-------------|----------| +| Clone into Docker volume | Ephemeral, lost on restart | | +| Mount host repo dirs | Repos at ~/Razer/* mounted directly into container | ✓ | +| Hybrid clone + mount | Some repos cloned, some mounted | | + +**User's choice:** Mount host repo dirs directly +**Notes:** Repos live at `~/Razer/rai-ops`, `~/Razer/rai-deployment`, `~/Razer/rai-devtools`. Mounted read-write per folder. Host-side git worktrees are preserved — no re-cloning needed. + +--- + +## Init Script + +| Option | Description | Selected | +|--------|-------------|----------| +| Ok | session-init.sh in ~/.hermes/scripts/ | ✓ | + +**User's choice:** Approved as proposed +**Notes:** Script goes in `~/.hermes/scripts/session-init.sh`, configured via `shell_init_files`. + +--- + +## Default Repos List + +| Option | Description | Selected | +|--------|-------------|----------| +| rai-ops, rai-deployment, rai-devtools only | 3 repos on Bitbucket razersw workspace | ✓ | + +**User's choice:** These 3 for now, but wants it configurable +**Notes:** DEFAULT_REPOS as env var in .env so user can add/remove without editing the script. + +--- + +## Configurability + +| Option | Description | Selected | +|--------|-------------|----------| +| Hardcoded in script | Simple but requires editing script to change | | +| Env var in .env | Configurable by editing .env | ✓ | +| Config file | Dedicated config file | | + +**User's choice:** Env var in .env +**Notes:** `DEFAULT_REPOS=rai-ops,rai-deployment,rai-devtools` in `~/.hermes/.env`, forwarded into Docker via `docker_forward_env`. + +--- + +## the agent's Discretion + +- Init script error handling (non-blocking on missing repos) +- On-demand clone destination (default to /workspace/) + +## Deferred Ideas + +- Per-repo deploy keys for future security hardening +- Auto-register repos as git worktrees (already handled host-side)