docs(06): capture phase context
This commit is contained in:
119
.planning/phases/06-default-repos-ssh-mount/06-CONTEXT.md
Normal file
119
.planning/phases/06-default-repos-ssh-mount/06-CONTEXT.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# Phase 6: Default Repos & SSH Mount - Context
|
||||
|
||||
**Gathered:** 2026-06-14
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## 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
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## 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/<repo>` 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/<name>`, 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/<repo>.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
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## 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
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## 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)
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## 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
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## 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
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 6-Default Repos & SSH Mount*
|
||||
*Context gathered: 2026-06-14*
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user