> **COMPULSORY — read [`MANUAL.md`](MANUAL.md) before implementing any feature.**
> It defines *how we build*: living architecture (the unit of work is "reshape
> the codebase so the feature fits, then build it"), the seam-vs-machinery rule,
> the duty to **stop and flag** when the current shape won't hold a feature
> cleanly, and the wireframe-in-chat habit. Reason from it; don't bolt features
> onto a misshapen base.

codealmanac is a living wiki for codebases, maintained by AI coding agents. It documents what the code can't say — decisions, flows, invariants, incidents, gotchas — as atomic, interlinked markdown pages living in a configurable repo-local Almanac root. New Python repos default to `almanac/`; users can choose `docs/almanac/` or explicit `.almanac/` during setup. Primary consumer is the AI coding agent; humans benefit secondarily.

**Full spec:** `/Users/rohan/Desktop/Projects/openalmanac/docs/ideas/codebase-wiki.md` — source of truth. Read it before making design changes. This file is the working context for implementation.

## Python rewrite architecture references

The active rewrite is a local-only Python codebase. Before non-trivial Python
implementation, read `docs/python-port-live-agreement.md` and the relevant
local Architecture Patterns with Python chapters under
`docs/reference/cosmic-python/`.

Use the book as architecture reference, not as a package template. The main
transfer is: services own product verbs, stores own persistence, ports live
near the service that owns the contract, integrations implement those ports,
and `src/codealmanac/app.py` is the composition root.

Useful chapter map:

- Persistence/store boundaries: `chapter_02_repository.md`
- CLI/API-to-service boundary: `chapter_04_service_layer.md`
- Service-level tests: `chapter_05_high_gear_low_gear.md`
- Transaction boundaries: `chapter_06_uow.md`
- Command/request objects: `chapter_10_commands.md`
- Composition root/dependency wiring: `chapter_13_dependency_injection.md`

When a Cosmic Python idea justifies a design choice, quote the relevant line
briefly in the plan or response and cite the local chapter path. Keep the
generated Markdown reference files as book text; CodeAlmanac notes belong in
`docs/reference/cosmic-python/CODEALMANAC.md`, repo docs, or wiki pages.

## Design philosophy

Intelligence lives in prompts, not pipelines. When judgment is needed — deciding what a session produced, scoring notability, evaluating a proposed page against the graph — we hand a concrete-but-open prompt to an agent. We do not wrap agents in propose/review/apply state machines, intermediate proposal files, or `--dry-run` rehearsals. The writer owns outcomes and calls the reviewer as a subagent when it wants feedback; there is no orchestration JSON schema between them. Everything is **local-only**: each repo has one configured Almanac root, `~/.almanac/registry.json` is global state, and there is no hosted service in this v1. The configured root is **flat**: no nested `wiki/` subdir, and future features get peer files. Only lifecycle operations invoke AI or write page prose. Read commands may refresh derived local index state and read committed markdown for display or validation. Organization commands may deterministically rewrite wiki metadata through explicit verbs such as `tag`, `topics`, `review`, and `migrate`.

## Engineering taste

There is no prize for preserving awkward code. Prefer the structure a new maintainer would understand immediately.

- Prefer obvious architecture over local patching when a bug exposes mixed responsibilities.
- Before accepting a solution, ask whether it creates a one-off mechanism where the existing general model could be extended instead. If it does, require an explicit architectural justification: why the general path is insufficient, whether the exception is temporary or permanent, how it is bounded, and what would make it safe to remove or generalize later.
- Existing special conditions are not automatically legitimate just because they are already in the codebase. This project has been built with AI, and AI agents can leave behind locally effective one-off fixes that were never consciously accepted as architecture. Treat extra flags, copied files, fallback paths, bespoke state, provider-specific branches, and helper scripts as provisional until they earn their place.
- Weight special cases by cost and evidence. Do not remove them reflexively; compatibility, migration, safety, platform, and provider constraints can be real. But a narrow exception with high maintenance cost needs stronger justification than a small localized shim.
- Assume the agents using this repo are capable: they can read files, inspect history, follow wiki pages, call tools, and reason over context. Do not build rigid preprocessing, copied context bundles, artificial staging files, or elaborate orchestration solely because an agent might need help. Prefer giving the agent real source material and a clear contract unless there is evidence that the general agentic workflow fails.
- This is an open-source project, so every new tracked file is public surface area and future maintenance burden. Before adding a file, ask who will own it, whether it belongs in an existing prompt/doc/module, and what keeps it from becoming stale.
- Keep modules honest: a file named `auth.py` should not secretly mean "Claude auth"; a central status file should not know provider-specific details.
- Short files are good, but responsibility boundaries matter more than line count. Split when a file has multiple reasons to change.
- Delete dead compatibility layers once callers have moved. Compatibility shims are temporary bridges, not architecture.
- When code feels ugly, treat that as design feedback. Naming, file shape, and import direction are part of correctness because they teach future agents how to extend the system.



## Codebase map

| Directory | What it is | Key files |
|-----------|-----------|-----------|
| `archive/code/` | Archived TypeScript/Node implementation and old viewer | behavior reference only |
| `docs/python-port-live-agreement.md` | Active Python rewrite agreement | local-only scope, service/workflow/integration structure |
| `docs/reference/cosmic-python/` | Vendored Architecture Patterns with Python reference | Markdown-only book files plus `CODEALMANAC.md` |
| `.almanac/` | This repo's current working wiki | `README.md`, `pages/`, `topics.yaml` |
| `src/codealmanac/` | Active Python implementation root | `app.py`, `cli/`, `services/`, `workflows/`, `integrations/` |
| `tests/` | Active Python test suite | pytest files plus temp-home helpers |
| `.github/` | GitHub workflow and contribution metadata | CI/publish templates may need rewrite after Python scaffold |

## How we work

### Slice-by-slice

Implementation is split into numbered slices. Each slice gets a plan in `docs/plans/slice-N-*.md` written before code. The plan states scope, out-of-scope, design decisions, file changes, test coverage, and explicit "Read before coding" pointers. After a slice lands, a review finds bugs and omissions; fixes go in a separate `docs/plans/fixes-slice-N-review.md` plan and ship as their own commit. **Write the plan, build, review, fix, then move to the next slice.** Don't collapse slices to save a step — the review pass is where latent bugs surface.

Plans use **must-fix / should-fix / consider** framing for review findings. Must-fix = correctness or contract bug. Should-fix = consistency, structure, or edge case that will bite later. Consider = taste call worth flagging, author decides.

### Background agents

When tasks are independent (e.g., "write slice-3 plan" and "draft reviewer prompt"), dispatch multiple subagents in parallel. Don't serialize work that doesn't need serializing.

### Code review

When the user asks for a code review or reviewer, read `.claude/agents/review.md` first and treat it as the authoritative code-review prompt for this repo. Do not confuse it with `prompts/reviewer.md`, which is the wiki reviewer subagent used by Absorb.

Use code review after meaningful structural changes, especially changes to command flows, provider boundaries, indexer behavior, SQLite queries, prompt contracts, or filesystem writes. The review standard is not "does it pass tests?" but "would a fresh maintainer understand why this is the obvious shape?"

### Commit conventions

- `feat(slice-N): <summary>` — new slice landing
- `fix(slice-N-review): <summary>` — review fixes for slice N
- `docs: <summary>` — plans, research, README, this file
- `refactor(slice-N): <summary>` — structural cleanup within a slice's surface area

Keep commits buildable and test-passing. Use the Python gates defined in this
repo rather than the archived Node/Vitest commands.

### Testing

Use `uv run pytest` and `uv run ruff check .` as the default gates. Tests that touch user-level state must sandbox `HOME` and never touch the real user registry. The archived Vitest suite under `archive/code/test/` is behavior reference only.

## Design decisions

_Cross-cutting architectural choices. Keep current, concise, and explanatory. Update this when a conversation settles a structural choice._

- **CLI is an adapter, not the internal API.** CLI dispatch builds request objects and calls the app composition root. Workflows, automation, tests, and future server wrappers call services/workflows directly.
- **Workspace owns repo selection and Almanac roots.** The configured repo-local root defaults to `almanac/`; `docs/almanac/` and `.almanac/` are explicit setup choices.
- **Stores own persistence behavior.** Shared SQLite mechanics live in `codealmanac.database`; store packages own schemas, migrations, queries, and row conversion.
- **Integrations implement service-owned ports.** Harnesses, transcript discovery, source runtime, Git probes, and scheduler adapters stay behind service/workflow contracts.
- **Review prompts are separate by job.** `src/codealmanac/prompts/operations/garden.md` and `ingest.md` guide wiki writes; `.claude/agents/review.md` reviews code architecture and implementation.

## Non-negotiables

Design rules every change must respect. The spec has the full rationale; these are the ones that trip people up.

- **Only lifecycle operations invoke AI or write page prose.** Read commands may refresh derived local index state and read committed markdown for display or validation. Organization commands may deterministically rewrite wiki metadata through explicit verbs such as `tag`, `topics`, `review`, and `migrate`.
- **Reindex is silent and implicit.** Every query command compares `pages/*.md` mtimes against `index.db` and rebuilds if stale. No progress bars, no "indexing..." chatter, no opt-in flag. `codealmanac reindex` is the escape hatch for "I want to force it."
- **Unified `[[...]]` syntax.** One link form, disambiguated by content: contains `:` before `/` → cross-wiki; contains `/` → file ref (trailing `/` = folder); otherwise → page slug. Do not introduce a second link syntax.
- **Use `GLOB` not `LIKE` for path queries**, and **escape `*?[` before concatenating stored paths into a GLOB pattern.** SQLite's `LIKE` treats `_` as a wildcard (spurious matches on `src/my_module/`); `GLOB` treats it literally. A Next.js-style stored path like `src/[id]/page.tsx` contains GLOB metacharacters — unescaped, it matches things it shouldn't. See `fixes-slice-2-review.md` for the bug and fix.
- **Paths are normalized at index time and at query time.** Lowercase (macOS is case-insensitive), forward slashes, no `./` prefix, trailing slash iff directory, no redundant slashes. Normalize on both sides of a comparison.
- **Slugs are kebab-case of the filename.** `checkout_flow`, `Checkout Flow.md`, `checkout-flow.md` all canonicalize to `checkout-flow`. Enforced at write time and checked by health.
- **DAG cycle prevention is belt-and-suspenders.** `CHECK (child_slug != parent_slug)` in the schema, pre-insert cycle check on `topics link`, and a depth cap of 32 on any recursive CTE.
- **Workspace roots are configurable.** New repos default to `almanac/`. `docs/almanac/` and `.almanac/` are valid only when configured during setup or already recorded in the registry. Downstream code must use `Workspace.almanac_path` rather than concatenating a literal root.
- **Registry entries are never auto-dropped.** Unreachable paths are silently skipped in `--all` queries. `codealmanac list --drop <name>` is the only explicit removal.
- **Archived pages are excluded from search by default**, are not flagged for dead-refs by `health`, and keep their backlinks resolvable. `--include-archive` and `--archived` change scope.
- **Prompts and manual docs are shipped as Python package resources.** They live under `src/codealmanac/prompts/` and `src/codealmanac/manual/`. They are not embedded as Python string literals.

## Philosophy anti-patterns

Things we do not do. If a plan proposes one, push back.

- **No propose/apply flows.** No proposal JSON files, no `--apply` or `--confirm` step. Agents write directly; users read the diff in `git status`.
- **No `--dry-run` flags.** The agent is either doing the work or it isn't. Rehearsal is not a feature.
- **No interactive prompts.** The CLI is pipeable and scriptable; scheduled sync runs in the background. Nothing blocks on user input.
- **No pipeline scaffolding where a prompt would do.** If a task calls for judgment, extend the prompt — don't add a pre-processing step in TypeScript that hard-codes the judgment.
- **No state machines between writer and reviewer.** Writer invokes reviewer via `agents: { reviewer }` in the SDK, reads the text critique, decides. No approve/revise/reject enum.
- **No semantic search yet.** FTS5 first. Add vectors only when FTS5 proves insufficient against a real repo.
- **No raw `codealmanac query`.** The schema is simple; open `index.db` directly if you need to.
- **No `codealmanac read/write/edit`.** The agent has Read/Write/Edit tools.

## Key file locations

- **Design spec:** `/Users/rohan/Desktop/Projects/openalmanac/docs/ideas/codebase-wiki.md`
- **Python port agreement:** `docs/python-port-live-agreement.md`
- **Slice notes:** `docs/python-port/slice-*.md`
- **Prompts:** `src/codealmanac/prompts/`
- **Manual resources:** `src/codealmanac/manual/`
- **SQLite schema/read model:** `src/codealmanac/services/index/store.py`
- **Init/build scaffolding:** `src/codealmanac/services/wiki/service.py`
- **Workspace roots and registry:** `src/codealmanac/services/workspaces/`
- **CLI edge:** `src/codealmanac/cli/`
- **Test sandbox helpers:** `tests/conftest.py`
