feat(my-deepagent): v0.1.0 Step 0~5 — scaffolding through deepagent + OpenRouter

Python rewrite of the agent harness on top of deepagents 0.6.1 + langchain 1.x,
replacing the abandoned TS attempt in packages/. 388 unit/integration tests pass.

Steps
-----
0. Scaffolding — uv workspace, ruff/mypy/pre-commit/alembic, src/tests/docs
   trees with docs/schemas/ seeded from my-deepagent-seed/.
1. Core — config (pydantic-settings with MYDEEPAGENT_ env prefix and TOML
   source), enums (Backend, Capability, RiskLevel, ApprovalDecisionAction,
   ApprovalState, RunState, RunPhaseState, SessionState, ErrorClass),
   errors (MyDeepAgentError + BudgetExhaustedError with PEP-3134 cause +
   context suppression), hash (canonical JSON + sha256).
2. Persona/Workflow/Binding — pydantic v2 schemas with tuple-based deep
   immutability (post-construction hash drift prevented), YAML loaders,
   deterministic auto-select (preferred_backends → version → name → hash),
   override resolution with ineligibility diagnostics, PersonaConsentStore
   with fcntl.flock + tmp+fsync+rename atomic write.
3. Artifact schema registry — Draft202012Validator, multi-root resolution,
   structured ValidationFinding output.
4. Persistence — 18 SQLAlchemy 2.0 async ORM models with FK CASCADE/RESTRICT,
   WAL + busy_timeout + foreign_keys PRAGMA, alembic baseline +
   ux_active_run_repo_base partial unique index, LangGraph SqliteSaver as
   context manager only (lifecycle safety).
5. DeepAgent session — build_agent wires Persona → create_deep_agent with
   LocalShellBackend / FilesystemBackend / StateBackend / CompositeBackend,
   ChatOpenAI(base_url=openrouter) for openrouter: model strings, and 4
   middleware classes (cost / audit-tool / safety-shell / fallback-model).

Critical workarounds
--------------------
- deepagents 0.6.1 rejects FilesystemPermission together with backends that
  implement SandboxBackendProtocol (LocalShellBackend). SafetyShellMiddleware
  enforces destructive-command and secret-path policy at the tool layer
  instead, and build_agent strips the permissions kwarg when the persona's
  deepagents_backend is local_shell.
- FilesystemOperation in deepagents is Literal['read', 'write'] only;
  _map_operations collapses our richer schema (read/write/edit/ls) safely.

Real OpenRouter smoke
---------------------
test_openrouter_deepagents_local_shell_smoke calls DeepSeek via deepagents +
LocalShellBackend + SafetyShellMiddleware end-to-end. PASS, ~$0.000001 cost,
input=9 / output=1 tokens with content "OK".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

my-deepagent/docs/schemas/workflows/bug-fix-with-reproduction@1.yaml

@@ -0,0 +1,108 @@
+name: bug-fix-with-reproduction
+version: 1
+description: "버그 재현 → 진단 → 수정 → 검증. 각 단계 artifact 생성."
+roles:
+  - id: reproducer
+    required_capabilities:
+      - evidence_check
+    preferred_backends:
+      - openrouter
+    fallback_personas:
+      - "openrouter-claude-debugger@1"
+      - "openrouter-deepseek-log-analyzer@1"
+  - id: debugger
+    required_capabilities:
+      - code_edit
+      - evidence_check
+      - command_execute
+    preferred_backends:
+      - openrouter
+    fallback_personas:
+      - "openrouter-claude-debugger@1"
+  - id: fixer
+    required_capabilities:
+      - code_edit
+      - test_first_development
+    preferred_backends:
+      - openrouter
+    fallback_personas:
+      - "openrouter-claude-code-editor@1"
+  - id: verifier
+    required_capabilities:
+      - evidence_check
+      - objective_eval
+    preferred_backends:
+      - openrouter
+    fallback_personas:
+      - "openrouter-deepseek-verifier@1"
+phases:
+  - key: reproduce
+    title: "버그 재현 및 재현 조건 문서화"
+    risk: low
+    role: reproducer
+    expected_artifact:
+      path: artifacts/reproduction.json
+      schema: dev/spec@1
+    gates:
+      - reproduce_approved
+    timeout_seconds: 300
+    instructions: |
+      보고된 버그를 재현하고 재현 조건을 문서화합니다.
+      로그 파일이 있으면 read_file로 읽고 패턴을 분석합니다.
+      glob/grep으로 관련 코드를 검색합니다.
+      재현 조건·환경·입력값·실제 출력·기대 출력을 dev/spec@1 형식으로
+      artifacts/reproduction.json에 write_file로 저장합니다.
+    max_budget_usd: 0.20
+  - key: diagnose
+    title: "근본 원인 진단"
+    risk: low
+    role: debugger
+    expected_artifact:
+      path: artifacts/diagnosis.json
+      schema: dev/spec@1
+    gates:
+      - diagnose_approved
+    timeout_seconds: 360
+    instructions: |
+      artifacts/reproduction.json을 read_file로 읽고 근본 원인을 진단합니다.
+      가설을 세우고 read_file/grep으로 코드에서 검증합니다.
+      가장 단순한 가설부터 검증합니다.
+      root cause, 영향 범위, 수정 제안을 dev/spec@1 형식으로
+      artifacts/diagnosis.json에 write_file로 저장합니다.
+    max_budget_usd: 0.50
+  - key: fix
+    title: "버그 수정"
+    risk: medium
+    role: fixer
+    expected_artifact:
+      path: artifacts/fix.json
+      schema: dev/spec@1
+    gates:
+      - fix_approved
+    timeout_seconds: 600
+    instructions: |
+      artifacts/diagnosis.json을 read_file로 읽고 근본 원인을 수정합니다.
+      수정 전 테스트 케이스를 먼저 작성합니다 (test_first_development).
+      edit_file로 최소한의 변경만 적용합니다.
+      수정 내용, 변경된 파일 목록, 테스트 명령어를 dev/spec@1 형식으로
+      artifacts/fix.json에 write_file로 저장합니다.
+    max_budget_usd: 1.00
+  - key: verify
+    title: "수정 결과 검증"
+    risk: low
+    role: verifier
+    expected_artifact:
+      path: artifacts/verification.json
+      schema: dev/review-finding-batch@1
+    gates:
+      - verify_approved
+    timeout_seconds: 300
+    instructions: |
+      artifacts/fix.json을 read_file로 읽고 수정된 코드를 직접 확인합니다.
+      재현 조건이 해소됐는지, 회귀 위험은 없는지 검증합니다.
+      검증 결과를 dev/review-finding-batch@1 형식으로
+      artifacts/verification.json에 write_file로 저장합니다.
+      verifierStatus: confirmed = 수정 확인됨, rejected = 수정 불충분.
+    max_budget_usd: 0.20
+default_gates: []
+max_total_budget_usd: 3.0

my-deepagent/docs/schemas/workflows/code-investigation@1.yaml

@@ -0,0 +1,63 @@
+name: code-investigation
+version: 1
+description: "코드베이스 탐색 → 요약 보고서 생성. 구조 파악·의존성 분석·이슈 발굴."
+roles:
+  - id: explorer
+    required_capabilities:
+      - evidence_check
+      - code_review
+    preferred_backends:
+      - openrouter
+    fallback_personas:
+      - "openrouter-claude-code-reviewer@1"
+      - "openrouter-deepseek-verifier@1"
+  - id: summarizer
+    required_capabilities:
+      - evidence_check
+      - final_report_compose
+    preferred_backends:
+      - openrouter
+    fallback_personas:
+      - "openrouter-claude-spec-writer@1"
+phases:
+  - key: explore
+    title: "코드베이스 탐색 및 정보 수집"
+    risk: low
+    role: explorer
+    expected_artifact:
+      path: artifacts/exploration.json
+      schema: dev/spec@1
+    gates: []
+    timeout_seconds: 600
+    instructions: |
+      코드베이스를 체계적으로 탐색합니다.
+      glob으로 전체 파일 구조를 파악하고 read_file로 핵심 파일을 읽습니다.
+      grep으로 주요 패턴·의존성·진입점을 검색합니다.
+      발견한 내용 (구조, 주요 컴포넌트, 의존성, 잠재적 이슈)을
+      dev/spec@1 형식으로 artifacts/exploration.json에 write_file로 저장합니다.
+      requirements 필드: 탐색 목적
+      approach 필드: 탐색한 파일 목록 및 방법
+      acceptance_criteria 필드: 발견한 핵심 사실들
+      risks 필드: 발견한 잠재적 이슈들
+    max_budget_usd: 0.50
+  - key: summarize
+    title: "탐색 결과 최종 보고서 작성"
+    risk: low
+    role: summarizer
+    expected_artifact:
+      path: artifacts/report.json
+      schema: common/final-report@1
+    gates:
+      - report_approved
+    timeout_seconds: 300
+    instructions: |
+      artifacts/exploration.json을 read_file로 읽고 common/final-report@1 형식으로
+      최종 보고서를 작성합니다.
+      status: "completed"
+      phases: explore와 summarize 단계 정보
+      findings: exploration.json의 risks 항목을 finding으로 변환
+      artifacts: exploration.json 경로 포함
+      보고서를 write_file로 artifacts/report.json에 저장합니다.
+    max_budget_usd: 0.30
+default_gates: []
+max_total_budget_usd: 1.0

my-deepagent/docs/schemas/workflows/spec-and-review@1.yaml

@@ -0,0 +1,76 @@
+name: spec-and-review
+version: 1
+description: "요구사항 → spec → 리뷰 → verifier 검증"
+roles:
+  - id: spec_writer
+    required_capabilities:
+      - spec_write
+      - phase_planning
+    preferred_backends:
+      - openrouter
+    fallback_personas:
+      - "openrouter-claude-spec-writer@1"
+  - id: reviewer
+    required_capabilities:
+      - code_review
+      - evidence_check
+    preferred_backends:
+      - openrouter
+    fallback_personas:
+      - "openrouter-claude-code-reviewer@1"
+  - id: verifier
+    required_capabilities:
+      - evidence_check
+      - objective_eval
+    preferred_backends:
+      - openrouter
+    fallback_personas:
+      - "openrouter-deepseek-verifier@1"
+phases:
+  - key: spec
+    title: "요구사항 분석 및 Spec 작성"
+    risk: low
+    role: spec_writer
+    expected_artifact:
+      path: artifacts/spec.json
+      schema: dev/spec@1
+    gates:
+      - spec_approved
+    timeout_seconds: 300
+    instructions: |
+      사용자 요구사항을 분석해 dev/spec@1 schema에 맞는 spec.json을 작성하세요.
+      기존 코드는 read_file/glob/grep으로 탐색합니다.
+      완성된 spec.json은 write_file로 artifacts/spec.json에 저장합니다.
+    max_budget_usd: 0.50
+  - key: review
+    title: "Spec 리뷰"
+    risk: low
+    role: reviewer
+    expected_artifact:
+      path: artifacts/review.json
+      schema: dev/review-finding-batch@1
+    gates:
+      - review_approved
+    timeout_seconds: 300
+    instructions: |
+      artifacts/spec.json을 read_file로 읽고 dev/review-finding-batch@1 형식으로 review.json을 작성하세요.
+      각 finding은 severity, category, summary를 반드시 포함합니다.
+      완성된 review.json은 write_file로 artifacts/review.json에 저장합니다.
+    max_budget_usd: 0.50
+  - key: verify
+    title: "리뷰 결과 검증"
+    risk: low
+    role: verifier
+    expected_artifact:
+      path: artifacts/verification.json
+      schema: dev/review-finding-batch@1
+    gates:
+      - verify_approved
+    timeout_seconds: 180
+    instructions: |
+      artifacts/review.json을 read_file로 읽고 각 finding을 코드에서 직접 확인합니다.
+      verifierStatus를 confirmed 또는 rejected로 판정하고 근거를 evidence 필드에 기록합니다.
+      결과를 write_file로 artifacts/verification.json에 저장합니다.
+    max_budget_usd: 0.10
+default_gates: []
+max_total_budget_usd: 2.0