init: seed Ratatoskr from corviduo-project-template + ship v0 scaffold
Worldtree Conversation API debug TUI. Multi-pane observability dashboard: chat transcript + persona/Vili affect log + tool events + admin events + Bifrost state + tool inventory + (opt-in) raw server log. Design locked at docs/design-brief.md (originated as brokkr-smithy/docs/ratatoskr-design-brief.md). Operator-locked decisions: - Textual application-shell framework (multi-pane dashboard, not REPL). - Separate repo + separate dev team (no Worldtree-source imports). - httpx-sse for SSE consumption (reference Python SSE-resume impl). - Triple version-skew mitigation: spec-pin in pyproject.toml + recorded SSE snapshot tests + conformance smoke. Initial pin: Worldtree v0.19.0 at 55101e909abcd2219833266b6f905c5bc956e0f0. - Persona pane: label-don't-refuse PII posture. - Server-log pane: opt-in via --server-log <path>. - Two-stage Ctrl-C (cancel then exit). - Markdown rendering default-on; --raw opt-out. In the box: - docs/design-brief.md — the locked design with full rationale. - docs/SPEC-PIN.md — Worldtree spec pin + bump procedure. - docs/conversation-api-spec.md + docs/conversation_api.contract.md — vendored Worldtree spec snapshots at the pinned SHA. - pyproject.toml — Python 3.12, hatchling, uv-managed, deps locked. - src/ratatoskr/ — stub package (cli.py raises NotImplementedError). - tests/test_no_worldtree_imports.py — boundary smoke test PASSING. - tests/snapshots/README.md — recording convention for SSE snapshot tests. Not in the box yet: - Gitea remote (operator/infra-ops to register at vh/ratatoskr). - Implementation — the dev team owns this; design brief is the spec. Origin: althing thread 01KS3R34XD3N6HMK91VXESHGW7 (worldtree-dev → brokkr-smithy-dev, 2026-05-20). Volva consulted via thread 01KS3VF6W33N3V5FNMGQ91YNVD.
This commit is contained in:
@@ -0,0 +1,67 @@
|
||||
# Principles
|
||||
|
||||
Four principles governing engineering choices across all Corviduo
|
||||
projects. Common lodestar: **fitness-for-purpose**. Each principle
|
||||
rejects a different substitute goal that disguises itself as virtue.
|
||||
|
||||
These are user-level defaults that originate at `~/.claude/CLAUDE.md`,
|
||||
duplicated here so they live with the codebase and are visible to
|
||||
humans browsing the repo (or AI tooling that doesn't load the
|
||||
user-level CLAUDE.md). When the user-level statement is amended,
|
||||
this file is backported.
|
||||
|
||||
---
|
||||
|
||||
## 1. Excellence over uniqueness
|
||||
|
||||
Pick the shape that's right for the problem, not the shape that's new.
|
||||
If uniqueness is a byproduct of excellence, so be it; do not target it.
|
||||
|
||||
*Rejects:* novelty-as-goal.
|
||||
|
||||
## 2. Explicit over implicit
|
||||
|
||||
Make load-bearing assumptions, constraints, and coupling visible.
|
||||
Idiomatic implicitness (language conventions, well-known protocols)
|
||||
is fine — the rule targets *invisible* implicitness, not all of it.
|
||||
Cost of explicitness is verbosity; cost of invisible implicitness is
|
||||
undetectable coupling. Pay the cost where auditability beats the tax.
|
||||
|
||||
*Rejects:* cleverness-as-goal.
|
||||
|
||||
## 3. Elegance is a byproduct, not a target
|
||||
|
||||
Excellent engineering often produces elegant results; targeting
|
||||
elegance directly tends to produce cleverness, which is a different
|
||||
thing. Review test: *"fit-for-purpose, debuggable, consistent"* —
|
||||
not *"feels nice."*
|
||||
|
||||
*Rejects:* beauty-as-goal.
|
||||
|
||||
## 4. Action-relevance over thoroughness
|
||||
|
||||
Before investigating, ask whether the answer would change the action.
|
||||
If both outcomes lead to the same default, skip the question.
|
||||
|
||||
*Rejects:* thoroughness-as-goal.
|
||||
|
||||
---
|
||||
|
||||
## What this file is, and isn't
|
||||
|
||||
These principles are *what to optimize for*. They sit above two other
|
||||
layers:
|
||||
|
||||
| Layer | Where it lives | What it answers |
|
||||
|---|---|---|
|
||||
| **Principles** (this file) | `PRINCIPLES.md` + `~/.claude/CLAUDE.md` § Core principles | *What to optimize for* across all work |
|
||||
| **Behavioral guidelines** | `CLAUDE.md` § BEHAVIORAL GUIDELINES | *How to operate session-to-session* (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) |
|
||||
| **Workflow mechanics** | `CLAUDE.md` § Project conventions + the contract format, TDD cycle, etc. | *Project-level mechanics* (contracts-first, TDD vertical slices, no-backwards-compat-until-v1.x, persistent-memory commit-along) |
|
||||
|
||||
Don't conflate the three layers. Workflow rules tell you what to do
|
||||
mechanically; behavioral guidelines tell you how to think during a
|
||||
session; principles tell you what *good* looks like across all of it.
|
||||
|
||||
A workflow rule can be amended without touching the principle that
|
||||
motivates it. A principle changes rarely — when one does, it ripples
|
||||
through every other layer.
|
||||
Reference in New Issue
Block a user