vh
9703eb2b6b
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.
141 lines
5.4 KiB
Markdown
141 lines
5.4 KiB
Markdown
# Methodology
|
|
|
|
The Corviduo preferred development pipeline for non-trivial work:
|
|
|
|
```
|
|
(optional) Vor → (required) Contract → branch (direct or AFK TDD) → verify against contract → merge/commit
|
|
```
|
|
|
|
Each step front-loads work into the cheapest place to do it:
|
|
|
|
- **Vor** front-loads ambiguity-resolution so the contract is sharp.
|
|
- **Contract** front-loads design so implementation is mechanical.
|
|
- **TDD** binds the contract to executable verification, vertical slice first.
|
|
- **Audit** closes the loop: code is checked against the spec, not the spec against the code.
|
|
- **Commit** lands the artifact + the supporting record together.
|
|
|
|
The contract is the load-bearing artifact in every path. Vor sharpens it; TDD executes against it; the audit verifies against it; the commit ships it.
|
|
|
|
---
|
|
|
|
## 1. Vor (optional)
|
|
|
|
When the ask carries ambiguity, run `/vor <ask>` before drafting the
|
|
contract. Vor routes through the Vor UI sidecar and produces a
|
|
structured response file: assumptions, questions with recommendations,
|
|
devil's-advocate pushback.
|
|
|
|
The `/vor` skill carries a built-in fuzziness gate that helps decide
|
|
whether to invoke. Unambiguous asks (concrete verb + noun + scope)
|
|
skip Vor and go straight to the contract.
|
|
|
|
A contract whose ambiguity was resolved via Vor is **Vor-graduated**:
|
|
`vor_graduated: true` in frontmatter. Sleipnir's INV-032 reads this
|
|
flag at intake and skips the plan-converge phase in AFK dispatch,
|
|
since the design questions are already resolved.
|
|
|
|
## 2. Contract (required)
|
|
|
|
Before any non-trivial implementation. The contract is the source of
|
|
truth that code is written to satisfy — not documentation of existing
|
|
code.
|
|
|
|
- Format spec: [`docs/contracts/CONTRACT-FORMAT.md`](contracts/CONTRACT-FORMAT.md) (v2.1 current).
|
|
- Module contracts: `docs/contracts/<module>.contract.md`.
|
|
- Issue-scoped contracts: `docs/contracts/issues/<N>.contract.md`, which
|
|
additionally require a populated `prd:` block pinning the issue body
|
|
+ lock-in comment SHA hashes.
|
|
|
|
Function blocks carry `FN / BRIEF / PRE / POST / ERRORS / STATE / STEPS / TESTS`.
|
|
The TESTS section is the load-bearing artifact for step 3 — TDD reads
|
|
from there.
|
|
|
|
Skip the contract for: bug fixes that don't change signatures or
|
|
behavior, trivial helpers, config changes, doc-only changes (per
|
|
`CLAUDE.md` § Contract-first workflow).
|
|
|
|
## 3. Branch — direct or AFK TDD
|
|
|
|
From the contract, two execution paths. Both run red-green-refactor
|
|
against the contract's TESTS section per the `tdd` skill's
|
|
vertical-slice discipline — tracer bullet first, then incremental loop.
|
|
Never write all tests then all code (produces tests of *imagined*
|
|
behavior).
|
|
|
|
### Direct TDD
|
|
|
|
The developer writes the code RGR locally.
|
|
|
|
### AFK TDD (sleipnir-shaped)
|
|
|
|
For issue-scoped work, AFK dispatch via Sleipnir:
|
|
|
|
1. `/sleipnir-preflight <N>` validates the contract's `prd:` pin via
|
|
`scripts/contract_drift_check.py`, posts the canonical agent
|
|
preamble as a Gitea comment + pins it to the contract, then applies
|
|
the `ready-for-agent` label via `tea`.
|
|
2. Sleipnir's daemon picks up the labelled issue, spawns an agent into
|
|
a per-issue git worktree, drives plan → implement → review → fixup
|
|
→ merge → done → corpus.
|
|
3. Vor-graduated contracts skip the plan-converge phase per INV-032.
|
|
|
|
Pre-dispatch policy is hard: see `CLAUDE.md` § Issue → AFK dispatch
|
|
hygiene.
|
|
|
|
## 4. Verify against contract
|
|
|
|
The audit pass. `CONTRACT-FORMAT.md` § 6 (Audit protocol) defines the
|
|
nine-point structured verification:
|
|
|
|
1. Signature match
|
|
2. PRE enforcement
|
|
3. POST satisfaction
|
|
4. Step coverage
|
|
5. Error handling
|
|
6. Invariant preservation
|
|
7. Test coverage
|
|
8. Resume correctness
|
|
9. No extra behavior
|
|
|
|
- **Direct path**: the developer audits their own work, or a sibling
|
|
pass (codex-via-Volva, peer-review-via-althing) performs the audit.
|
|
- **AFK path**: Sleipnir's review phase invokes the audit
|
|
automatically; verdict gates fixup/merge.
|
|
|
|
## 5. Merge / commit
|
|
|
|
Audit-clean work merges to the project's main branch. Per `CLAUDE.md`
|
|
§ Persistent-memory + housekeeping commit-along rule,
|
|
`persistent-memory.md` rides with the merge if dirty. Same for any
|
|
housekeeping files where they exist (`HANDOFF-SUMMARY.md`,
|
|
`NEXT-STEPS.md`, `README.md`, `State-Of-Development.md`).
|
|
|
|
Atomic commits: one logical change per commit; new code + new tests +
|
|
doc updates ride together where they form a coherent unit. No
|
|
backwards-compat shims, deprecation periods, or rename aliases until
|
|
v1.x — when something is redesigned, the old code is deleted and all
|
|
references are updated in the same commit.
|
|
|
|
---
|
|
|
|
## What this file is, and isn't
|
|
|
|
This file describes the *pipeline*. Each step delegates to the
|
|
canonical that owns its mechanics:
|
|
|
|
| Step | Owned by |
|
|
|---|---|
|
|
| Vor | `/vor` skill (lives in Galdrabok) |
|
|
| Contract format | [`docs/contracts/CONTRACT-FORMAT.md`](contracts/CONTRACT-FORMAT.md) |
|
|
| TDD discipline | `tdd` skill |
|
|
| Sleipnir AFK | `/sleipnir-preflight`, `/sleipnir-scaffold` skills + Sleipnir daemon |
|
|
| Audit | `CONTRACT-FORMAT.md` § 6 |
|
|
| Commit hygiene | `PRACTICES.md` (slated to migrate from Galdrabok); `CLAUDE.md` § Persistent-memory commit-along |
|
|
| Principles | [`PRINCIPLES.md`](../PRINCIPLES.md) (what to optimize for across all of the above) |
|
|
|
|
This file is canonical at `corviduo-project-template/docs/methodology.md`
|
|
and pinned via `.corviduo-canonicals.toml`. When a derivative Corviduo
|
|
project seeds from the template, this file copies in alongside the rest
|
|
and is kept in sync by `scripts/canonical_sync.py` /
|
|
`scripts/canonical_drift.py`.
|