feat: align memory schema with team decisions (#38, #48, #52)

.env → .env.example

@@ -1,3 +1,7 @@
+# Docker remote debug (debugpy): pass into container, e.g. ROSA_DEBUGPY=1 ./demo.sh
+ROSA_DEBUGPY=
+ROSA_DEBUGPY_PORT=5678
+
 # LLM Provider: "openai" (default), "anthropic", or "ollama"
 LLM_PROVIDER=openai
 

.gitattributes

@@ -0,0 +1,13 @@
+* text=auto
+
+# ROS/Python execution files must use LF on all OSes.
+*.py text eol=lf
+*.sh text eol=lf
+*.bash text eol=lf
+*.zsh text eol=lf
+*.launch text eol=lf
+
+# Keep Windows script compatibility where needed.
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf

.gitignore

@@ -1,8 +1,16 @@
 .idea
-.vscode
+.vscode/*
+!.vscode/launch.json
 src/jpl_rosa.egg-info
 build/
 dist/
 __pycache__/
-docs
 .DS_Store
+.env
+logs/
+.specstory
+.catkin_tools/
+.devcontainer/
+devel/
+src/turtle_agent/scripts/memory/**/*.jsonl
+.venv/

.vscode/launch.json

@@ -0,0 +1,157 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal"
+        },
+        {
+            // 3단계: 컨테이너에서 ROSA_DEBUGPY=1 로 ./demo.sh 후 `start` 실행 →
+            // "[ROSA_DEBUGPY] listening..." 에서 대기하는 동안 이 구성으로 Attach.
+            // 포트는 demo.sh / ROSA_DEBUGPY_PORT 와 동일해야 함 (기본 5678).
+            // 대화형 에이전트: redirectOutput 끔 — 켜면 출력은 디버그 콘솔로 가고
+            // 터미널의 `>` 와 입력이 갈라져 디버그 콘솔에 자연어를 넣다 오류가 난다.
+            "name": "Python: Docker debugpy (attach)",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {
+                "host": "127.0.0.1",
+                "port": 5678
+            },
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}/src",
+                    "remoteRoot": "/app/src"
+                },
+                {
+                    "localRoot": "${workspaceFolder}/src/turtle_agent/scripts",
+                    "remoteRoot": "/app/devel/lib/turtle_agent"
+                }
+            ],
+            "justMyCode": false
+        },
+        {
+            "name": "Tests: All",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["discover", "-s", "tests/test_turtle_agent", "-p", "test_*.py"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Tests: test_turtle_agent (group)",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["discover", "-s", "tests/test_turtle_agent", "-p", "test_*.py"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Test: test_collision_geometry",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["tests.test_turtle_agent.test_collision_geometry"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Test: test_collision_monitor",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["tests.test_turtle_agent.test_collision_monitor"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Test: test_memory_converter",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["tests.test_turtle_agent.test_memory_converter"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Test: test_obstacle_store",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["tests.test_turtle_agent.test_obstacle_store"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Test: test_obstacle_tools",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["tests.test_turtle_agent.test_obstacle_tools"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Test: test_pose_hub",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["tests.test_turtle_agent.test_pose_hub"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Test: test_pose_logger",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["tests.test_turtle_agent.test_pose_logger"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Test: test_static_map_loader",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["tests.test_turtle_agent.test_static_map_loader"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Test: test_turtle_lifecycle",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["tests.test_turtle_agent.test_turtle_lifecycle"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "Test: test_world_builder",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "unittest",
+            "args": ["tests.test_turtle_agent.test_world_builder"],
+            "cwd": "${workspaceFolder}",
+            "python": "/usr/bin/python3.9",
+            "console": "integratedTerminal"
+        }
+    ]
+}

AGENTS.md

@@ -0,0 +1,119 @@
+# AGENTS.md
+
+이 문서는 `upstage-sesac-agentic-robotics` 프로젝트에서 에이전트가 작업을 시작할 때 가장 먼저 확인해야 하는 공용 진입점입니다.
+모든 작업은 이 문서의 절차와 규칙을 기본값으로 따릅니다.
+
+## 적용 범위
+
+- 저장소 전체(`.`)에 적용합니다.
+- 코드 수정, 문서 작성, 이슈 생성, 브랜치/커밋/PR 작업에 공통 적용합니다.
+
+## 작업 시작 순서
+
+1. 요청을 작업 유형으로 분류합니다.
+2. 아래 **핵심 참조 문서 맵**에서 해당 작업의 기준 문서를 선택합니다.
+3. 선택한 기준 문서의 절차와 체크리스트를 따라 작업합니다.
+4. 완료 전 범위 이탈, 규칙 누락, 검증 결과를 확인합니다.
+
+## docs 문서 관리 원칙
+
+### 파일명 규칙
+
+- `docs`의 파일명은 한글 기준으로 작성합니다.
+- 파일명 구분자는 하이픈(`-`)만 사용합니다. (공백/언더스코어 미사용)
+- 기본 형식은 `분류-주제.md`로 통일합니다.
+- 분류는 `규칙`, `가이드`, `절차`를 사용합니다.
+
+### 규칙과 가이드의 구분
+
+- `규칙`: 반드시 지켜야 하는 강제 기준입니다. (브랜치 정책, 승인 절차 등)
+- `가이드`: 작업 품질과 효율을 높이기 위한 권장 기준입니다. (문서 구성, 표현 방식 등)
+
+## 핵심 참조 문서 맵
+
+### 에이전트 개발 규칙
+
+- 파일: `docs/규칙-에이전트-개발.md`
+- 역할: 에이전트 유형 판별, 디렉토리 구조, 실행 진입점, 로깅, README·다이어그램 작성 기준 제공
+
+### 깃허브 운영 규칙
+
+- 파일: `docs/규칙-깃허브-운영.md`
+- 역할: 브랜치 전략, 이슈 생성 절차, 커밋 규칙, CI/CD 확인, PR 생성 절차를 단일 문서로 제공
+- 이슈 생성 방법 → Section 3 참조
+- 브랜치·커밋·푸시·PR 생성 방법 → Section 1·2·4·6 참조
+
+## 전역 작업 원칙
+
+### 언어 및 표현
+
+- 기본 응답 언어는 한국어를 사용합니다.
+- 요청 범위 내에서만 답변하고, 추가 제안은 필요 여부를 먼저 확인합니다.
+
+### 판단 방식
+
+- 추측성 결론을 피하고 근거 기반으로 보수적으로 판단합니다.
+- 근거가 부족하면 단정하지 않고 확인 필요 사항을 명시합니다.
+
+### 범위 관리
+
+- 기본 원칙은 최소 변경입니다.
+- 범위 밖 항목은 본 작업에 포함하지 않고 별도 항목으로 분리합니다.
+
+### 문서/보고서
+
+- 보고서 파일 생성은 사용자 요청 시에만 수행합니다.
+- 문서는 Markdown으로 작성하고, 요구 시 목차/참조목록을 포함합니다.
+- 코드 근거를 인용할 때는 경로와 행 정보를 함께 제공합니다.
+
+### 보안/민감정보
+
+- API 키, 토큰, `.env` 비밀값은 출력하거나 재노출하지 않습니다.
+- 민감정보 노출 가능성이 있으면 즉시 마스킹/교체 필요 사항을 안내합니다.
+
+## 브랜치·커밋·PR·이슈 실행 규칙
+
+### 작업 순서 강제 규칙
+
+- 이 프로젝트의 표준 작업 순서는 `issue → branch → commit → PR → review → merge`입니다.
+- 커밋, PR, 신규 작업 시작 시 반드시 선행 이슈를 먼저 참조합니다.
+- 선행 이슈가 없으면 이슈 생성을 먼저 완료한 후 작업을 진행합니다.
+
+### 브랜치 기본 전략
+
+- 기준 브랜치는 `main`, `dev`입니다.
+- 작업은 목적에 맞는 새 브랜치에서 시작합니다. 네이밍 규칙은 `docs/규칙-깃허브-운영.md` Section 1.2를 따릅니다.
+  - 에이전트 서브 기능: `feat/<agent-name>/<feature-name>`
+  - 단독 기능: `feat/<feature-name>`
+  - 버그 수정: `fix/<issue-name>`
+  - 기타: `etc/<task-name>`
+- `main`, `dev` 직접 커밋은 금지합니다.
+
+### 커밋/PR 규칙
+
+- `feat/*`, `fix/*`, `etc/*`는 기본적으로 `dev` 대상 PR을 생성합니다.
+- PR은 단일 주제 원칙을 준수합니다.
+- PR 생성 전 제목/본문 초안을 사용자에게 공유하고 명시적 승인 후 생성합니다.
+- 커밋 전 로컬 품질 검사(아래 섹션)를 완료한 상태에서 PR을 생성합니다.
+
+### 이슈 생성 규칙
+
+- 이슈 생성은 본인 판단에 따라 수행합니다.
+- 절차는 `docs/규칙-깃허브-운영.md` Section 3을 따릅니다.
+
+## 로컬 품질 검사
+
+### 디버깅 (VS Code)
+
+`.vscode/launch.json`에 두 가지 구성이 있다.
+
+| 구성 이름 | 사용 시점 |
+|---|---|
+| `Python Debugger: Current File` | 현재 열린 파일을 로컬에서 직접 실행·디버그 |
+| `Python: Docker debugpy (attach)` | Docker 컨테이너에서 `ROSA_DEBUGPY=1`로 `demo.sh` 실행 후 포트 5678에 attach |
+
+## 작업 완료 점검
+
+- 요청 범위를 벗어난 변경이 없는지 확인합니다.
+- 참조 문서 규칙을 누락 없이 반영했는지 확인합니다.
+- 테스트/검증 결과와 남은 리스크를 분리해 보고합니다.

Dockerfile

@@ -13,7 +13,15 @@ RUN apt-get update && apt-get install -y \
     python3.9 \
     python3-pip \
     curl \
-    build-essential
+    build-essential \
+    openssh-server
+
+RUN mkdir /var/run/sshd && \
+    echo 'root:ros' | chpasswd && \
+    sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config && \
+    sed -i 's/#PasswordAuthentication yes/PasswordAuthentication yes/' /etc/ssh/sshd_config
+
+EXPOSE 22
 
 # Install Rust (required for building tiktoken)
 RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
@@ -23,7 +31,7 @@ ENV PATH="/root/.cargo/bin:${PATH}"
 # RUN apt-get clean && rm -rf /var/lib/apt/lists/*
 # Upgrade pip first, then install packages
 RUN python3.9 -m pip install --upgrade pip
-RUN python3.9 -m pip install --break-system-packages python-dotenv catkin_tools
+RUN python3.9 -m pip install --break-system-packages python-dotenv catkin_tools debugpy
 RUN rosdep update && \
     echo "source /opt/ros/noetic/setup.bash" >> /root/.bashrc && \
     echo "alias start='catkin build && source devel/setup.bash && roslaunch turtle_agent agent.launch'" >> /root/.bashrc && \
@@ -32,14 +40,19 @@ RUN rosdep update && \
 COPY . /app/
 WORKDIR /app/
 
+# Windows CRLF → LF 변환 (Windows 호스트에서 빌드 시 shebang 깨짐 방지)
+RUN find /app -type f -name "*.py" -exec sed -i 's/\r$//' {} + && \
+    find /app -type f -name "*.launch" -exec sed -i 's/\r$//' {} +
+
 # Modify the RUN command to use ARG
 RUN /bin/bash -c 'if [ "$DEVELOPMENT" = "true" ]; then \
     python3.9 -m pip install --break-system-packages --ignore-installed --user -e .; \
     else \
     python3.9 -m pip install --break-system-packages --ignore-installed -U jpl-rosa>=1.0.8; \
     fi'
 
-CMD ["/bin/bash", "-c", "source /opt/ros/noetic/setup.bash && \
+CMD ["/bin/bash", "-c", "/usr/sbin/sshd && \
+    source /opt/ros/noetic/setup.bash && \
     roscore > /dev/null 2>&1 & \
     sleep 5 && \
     if [ \"$HEADLESS\" = \"false\" ]; then \

README.md

@@ -81,6 +81,19 @@ https://github.com/user-attachments/assets/77b97014-6d2e-4123-8d0b-ea0916d93a4e
 
 For detailed instructions on setting up and running the TurtleSim demo, please refer to our [TurtleSim Demo Guide](https://github.com/nasa-jpl/rosa/wiki/Guide:-TurtleSim-Demo) in the Wiki.
 
+### TurtleSim Obstacles
+
+The TurtleSim demo can load static obstacles into an in-process `ObstacleStore`
+before the agent conversation starts. Set `~static_obstacles_file` to a YAML or
+JSON map such as `src/turtle_agent/config/static_obstacles_turtlesim.yaml`.
+
+When `~draw_static_world` is enabled, a startup-only `rospy` world builder reads
+the same store snapshot and draws the static world with a temporary builder
+turtle. Runtime obstacle CRUD is managed through LangChain tools that update the
+same store directly. `static` obstacles remain until removed; `temporary`
+obstacles expire after their TTL. No HTTP layer is used for obstacle CRUD or
+initial map injection.
+
 
 ## IsaacSim Extension (Coming Soon)