init: seed framework reference content from agent-runtimes main repo

harnesses/contexts/code-methodology/v1/CLAUDE.md

@@ -0,0 +1,110 @@
+# Code Methodology Context
+
+## Best Practices Review
+
+Before starting any task:
+
+1. Check if `/best-practices/INDEX.md` exists
+2. If it exists, read it to see available topics
+3. Identify relevant topics for the current task:
+   - Python task → read `test-driven-development.md`, `spec-driven-development.md`
+   - Kubernetes task → read `kubernetes.md`
+   - Shell scripts → read `scripting.md`
+4. Read the relevant topic files from `/best-practices/`
+5. Apply those practices to your work
+
+If `/best-practices/` doesn't exist, proceed without — it's not mandatory.
+
+## Spec-Driven Development Workflow
+
+1. **Read the spec** — Read relevant files in `spec/` before writing any code
+2. **Write tests first** — Create test cases from spec requirements before implementing (see `best-practices/test-driven-development.md` and `best-practices/spec-driven-development.md` if available)
+3. **Implement iteratively** — Build implementation to satisfy tests and spec
+4. **Write session log** — Document what was accomplished, decisions made, and gotchas discovered
+
+## Conventions
+
+- **Python 3.12+** with type hints throughout
+- **Pydantic v2** for all data models and settings
+- **pytest** for testing with clear, descriptive test names
+- **Structured JSON logging** for all output
+- **Configuration via environment variables** — no hardcoded config
+- **No shell scripts inside containers** — use Python for error handling
+
+## Code Quality Rules
+
+- Do not add features, refactor code, or make improvements beyond what was asked
+- Validate inputs at system boundaries only, trust internal interfaces
+
+## Agent Safety Rules
+
+These rules exist because container agents have repeatedly made these mistakes in production runs.
+
+### Python Module Safety
+
+Never call `sys.exit()` at module level or inside `except ImportError` blocks. This causes import
+failures in other modules that import this one. Use a flag pattern instead:
+
+```python
+_HAS_OPENAI = True
+try:
+    import openai
+except ImportError:
+    _HAS_OPENAI = False
+```
+
+Check the flag at call time:
+
+```python
+def use_openai():
+    if not _HAS_OPENAI:
+        raise RuntimeError("openai is not installed")
+    ...
+```
+
+### Pydantic Validators
+
+- Use `@model_validator(mode='after')` when validation needs cross-field access or must fire for
+  default values
+- `@field_validator` only fires when a field is **explicitly provided** — it will not run for
+  fields that fall back to their default
+
+### File Editing Policy (CRITICAL)
+
+**NEVER use the Write tool on any file that already exists in /project.**
+
+This is the single most important rule. Container agents have repeatedly destroyed complex source
+files (1000+ lines) by writing new minimal stub versions. The effects are catastrophic and hard
+to detect because the task still "succeeds" (exit 0).
+
+The correct workflow for modifying any existing file:
+1. **Read** the file first (Read tool)
+2. **Edit** with targeted changes (Edit tool) — ONLY the specific function, class, or field
+3. **Never** rewrite an entire file from scratch with Write
+4. **Never** "simplify" or "restructure" a file unless that is the explicit task
+
+The Write tool is ONLY for creating brand-new files that do not yet exist.
+
+Other file management rules:
+- Never create backup copies of files or directories before modifying them
+- Edit files in place — do not create paths ending in `_orig`, `_old`, `_bak`, or `_backup`
+- Do not rename existing files or directories before modifying them
+- In automated runs there is no one to clean up junk directories
+
+### Async Test Patterns
+
+- Test functions for async code must be `async def` decorated with `@pytest.mark.asyncio`
+- A sync `def test_` function that calls an async function receives a coroutine object, not the
+  result — the test will silently pass without executing the async logic
+
+## Session Logging
+
+Write a session log to `/project/memory/log/<date>.<time>.md` (e.g., `2026-03-24.041500.md`) with:
+
+- **Summary**: One paragraph of what was accomplished
+- **Decisions**: Key choices made and reasoning
+- **Gotchas**: Issues discovered with topic tags (e.g., `[python]`, `[docker]`)
+- **Open Questions**: Unresolved items for follow-up
+- **Process Notes**: What worked well, areas for improvement
+
+Omit empty sections.

harnesses/contexts/code-methodology/v1/harness.yaml

@@ -0,0 +1,10 @@
+kind: context
+name: code-methodology
+version: 1
+description: "Coding methodology: spec-driven workflow, session logging, best practices"
+requires: []
+provides: [coding-agent]
+
+context_files:
+  - source: ./CLAUDE.md
+    target: /opt/harness/context/code-methodology/CLAUDE.md