Metadata-Version: 2.5
Name: albok
Version: 0.1.0
Summary: Albok — the fleet knowledgebase engine: the LLM-free knowledge store and retrieval package, plus the service that owns the store. Extracted from Worldtree (#412 follow-on; design record in docs/design/albok/).
Author: Vuong Hoang
License: Proprietary
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: chromadb>=0.5
Requires-Dist: gitpython>=3.1
Requires-Dist: httpx>=0.27
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: sentence-transformers>=3.0
Requires-Dist: torch>=2.0
Description-Content-Type: text/markdown

# Corviduo project template

Canonical scaffold for new Corviduo projects. Captures the conventions
that recur across `Worldtree`, `Skaldsong`, `vastai-app` (Vast Blue SEA),
`sleipnir`, `Vor`, `Galdrabok`, `task-board`, `althing`, and any
future sibling. When a new Corviduo project lands, copy this scaffold
in rather than re-deriving the shape from Worldtree by hand.

## What this template provides

| Path | Purpose |
|---|---|
| `CLAUDE.md` | Top-level Claude Code conventions (Think Before Coding · Simplicity First · Surgical Changes · Goal-Driven Execution + Corviduo conventions: contracts-first · no-backwards-compat-until-v1.x · persistent-memory + housekeeping commit-along · TDD cycle · Sleipnir AFK hygiene · task-board reporting). Project-name placeholder uses `albok` — search-and-replace after copy. |
| `PRINCIPLES.md` | The four Corviduo engineering principles (Excellence over uniqueness · Explicit over implicit · Elegance is a byproduct · Action-relevance over thoroughness). Canonical — copied as-is. |
| `persistent-memory.md` | Durable intent across context resets — skeleton with the four canonical sections (Repo purpose / Current state / Recent decisions / Tried and abandoned). Project-agnostic. |
| `ROADMAP.md` | Anti-creep roadmap skeleton — v1 target (3–7 capabilities) + parking lot + the feature-gate (default = parking lot) + creep-check. `albok` placeholder; content diverges per project (a skeleton like `persistent-memory.md`, not a byte-canonical). The discipline lives in user-global `CLAUDE.md` § "Roadmap discipline"; this file is its per-project instance. |
| `README.md` | Project README skeleton; `albok` placeholder. |
| `docs/architecture.md` | Top-level module map placeholder; project-agnostic structure. |
| `docs/methodology.md` | The Corviduo preferred development pipeline ((optional) Vor → (required) Contract → branch (direct or AFK TDD) → verify → merge/commit). Generic — copied as-is. |
| `docs/canonical-sync.md` | The canonical-sync pattern, mechanism (`.<project>-canonicals.toml` manifest + `canonical_sync.py` + `canonical_drift.py`), publisher / consumer adoption steps, v<N>→v<N+1> bump procedure, and documented adopters table (current: Worldtree, Galdrabok, Bifrost). Read when a project ships a canonical spec or pins against one. |
| `docs/CODEBASE-CONVENTION.md` | Convention for `docs/CODEBASE.md` navigation maps (v0.1, experimental, recommended-only). Adopt via canonical-sync pin when a project is large enough to warrant a map. |
| `docs/VERSIONING-POLICY.md` | Versioning policy for all projects — SemVer 2.0.0, the public-contract declaration, pre-release staging, dev labeling, release process. Copied as-is. |
| `docs/codex-dispatch-protocol.md` | Canonical schema for the codex-dispatch message + the `handshake-v1` write-window protocol. Adopters point here rather than re-declaring. |
| `docs/intent-line.md` | The `⟦INTENT⟧` / `⟦STATE⟧` / `⟦DECIDE⟧` marker convention + opt-in UserPromptSubmit hook (Ledger-legible per-session Goal / State / pending-decision signals). |
| `docs/althing-monitoring.md` | Inbound convention for interactive sessions: althing 2.0.0 herald + wake-listener (default), self-poll monitor (fallback). Mechanism lives in the althing repo. |
| `docs/contracts/CONTRACT-FORMAT.md` | The canonical contract spec (v2.1). Generic infrastructure — copied as-is. |
| `docs/contracts/contract_parser.py` | Validates and extracts structured fields from `.contract.md` files. Generic — copied as-is. |
| `docs/contracts/issues/` | Empty directory for issue-scoped contracts (`<N>.contract.md` shape). |
| `scripts/contract_drift_check.py` | Verifies issue-scoped contracts' `prd:` block hashes match the live tracker state. Generic — copied as-is. |
| `scripts/canonical_sync.py` | Operator-triggered canonical re-sync: fetches each pinned canonical from its source, writes the consumer copy, bumps the pin's hash + timestamp. |
| `scripts/canonical_drift.py` | Read-only drift verifier (CI-gating): flags any pin stale against its source or diverged from the pinned hash. Exits non-zero on drift. |
| `.sleipnir/config.yaml.template` | Sleipnir per-project config. `cp` to `.sleipnir/config.yaml` (gitignored) and edit. |
| `env.sh.template` | Environment variables template. `cp` to `env.sh` (gitignored) and fill in. |
| `.gitignore` | Python-project standards (uv/poetry/pdm/pip caches; Sleipnir per-project config; logs; data; venv; ruff/mypy caches; IDE; OS). |
| `.corviduo-canonicals.toml` | Self-pin manifest declaring the canonicals this repo owns + their pinned hashes; drives `canonical_sync.py` / `canonical_drift.py`. |
| `tests/` | Empty directory for the test suite. |
| `LICENSE` | Canonical proprietary license (all rights reserved). Copied as-is into new projects — Corviduo work is private; this LICENSE makes intent explicit at the repo level rather than relying on the legal "all rights reserved" default. |

## What this template does NOT provide

- Project-specific module structure (per-module `core/<name>/CLAUDE.md` files, etc.)
- Project-specific runtime (no `core/` package; no agents directory; no transports)
- An issue tracker adapter (`core.issues` is Worldtree-specific; build per-project as needed)
- A specific dependency manager — pick `uv` / `poetry` / `pdm` / bare `pip` and add the appropriate manifest after copy
- Project-specific Sleipnir config (the template ships a `config.yaml.template`; rename + edit per checkout)
- A specific LLM provider (the env.sh template enumerates options, none are mandatory)

## How to use

```bash
# 1. Copy the template into a new project location
PROJECT_NAME=myproject
cp -r /home/lkraven/development/corviduo-project-template "$HOME/development/$PROJECT_NAME"
cd "$HOME/development/$PROJECT_NAME"

# 2. Replace the albok placeholder
find . -type f \( -name '*.md' -o -name '*.yaml' -o -name '*.template' \) \
     -not -path './.git/*' -not -path './docs/contracts/CONTRACT-FORMAT.md' \
     -exec sed -i "s/albok/$PROJECT_NAME/g" {} +

# 3. Reset git history for this project
rm -rf .git
git init -q
git add -A
git commit -m "init: seed from corviduo-project-template"

# 4. Set up local environment
cp env.sh.template env.sh
$EDITOR env.sh                 # fill in values
cp .sleipnir/config.yaml.template .sleipnir/config.yaml
$EDITOR .sleipnir/config.yaml  # adjust per-project (gitignored)
python -m venv .venv
source .venv/bin/activate
source env.sh

# 5. Author the project-specific README + persistent-memory + architecture
$EDITOR README.md
$EDITOR persistent-memory.md
$EDITOR docs/architecture.md

# 6. (Optional) register with Gitea, add a remote, then push
git remote add origin "git@gitea.phasefinal.com:vh/$PROJECT_NAME.git"
git push -u origin main
```

## Maintenance

When the convention shifts in one Corviduo project (Worldtree usually leads
on tooling changes — Sleipnir hygiene, contract format, drift checker), the
canonical template is the place to backport. Workflow:

1. Identify the Worldtree commit that established the new convention.
2. Apply the equivalent change here.
3. Bump the template's version note in `CLAUDE.md` change-log section if the change is non-cosmetic.
4. Existing project copies are not auto-synced — operators pull selectively via `git diff` against the template path.

## Versioning

The template doesn't carry its own semver. The four load-bearing pieces
(`CLAUDE.md`, `CONTRACT-FORMAT.md`, `contract_parser.py`, `contract_drift_check.py`)
each have their own internal versioning where applicable. Pin the contract
format version in each project's frontmatter (`contract_version: "2.1"`).

## Sibling Corviduo projects (reference)

- [Worldtree](https://gitea.phasefinal.com/vh/Worldtree) — multi-agent framework (the canonical source)
- [Skaldsong](https://gitea.phasefinal.com/vh/skaldsong) — story-generation engine
- [Vast Blue SEA](https://gitea.phasefinal.com/vh/vastai-app) — multi-agent web app
- [Sleipnir](https://gitea.phasefinal.com/vh/sleipnir) — AFK orchestrator
- [Vor](https://gitea.phasefinal.com/vh/Vor) — pre-contract design partner UI
- [Galdrabok](https://gitea.phasefinal.com/vh/Galdrabok) — Sleipnir-preflight skill author
- [task-board](https://gitea.phasefinal.com/vh/task-board) — per-session web UI
- [althing](https://gitea.phasefinal.com/vh/althing) — _newest, seeded from this template 2026-05-07_
