Three Operation Architecture Implementation Plan

`codealmanac init` is the public command for the first wiki build. Internally it
starts a `build` operation. There are exactly three internal wiki operations:
`build`, `ingest`, and `garden`. `sync` is transcript intake that creates
`ingest` runs. `update` is product maintenance. `capture` is retired language.

## Ticket 13: Restore Three Operation Architecture
 
Goal: make `init` delegate to a model-backed `build` operation and make
`build`, `ingest`, and `garden` the only internal wiki operations.
 
Non-negotiables:
- `codealmanac init` is public.
- `codealmanac build` is not public.
- run records use only `build`, `ingest`, or `garden`.
- `sync` creates `ingest` runs and is not a run operation.
- Kushagra's prompt/manual material from commit `4c615718` is copied literally
  first and adapted only for Python/nested `almanac/` format.

rg -n "build should not remain|RunOperation\\.SYNC|capture|absorb|\\.almanac/pages|files:" notes.md implementation-tickets.md docs src/codealmanac/manual src/codealmanac/prompts

git add notes.md implementation-tickets.md docs/plans/2026-07-06-three-operation-architecture.md
git commit -m "docs: lock three operation architecture"

git show 4c615718:src/codealmanac/prompts/base/kernel.md > src/codealmanac/prompts/base/kernel.md
git show 4c615718:src/codealmanac/prompts/operations/init.md > src/codealmanac/prompts/operations/build.md
git show 4c615718:src/codealmanac/prompts/operations/ingest.md > src/codealmanac/prompts/operations/ingest.md
git show 4c615718:src/codealmanac/prompts/operations/garden.md > src/codealmanac/prompts/operations/garden.md
git show 4c615718:src/codealmanac/manual/README.md > src/codealmanac/manual/README.md
git show 4c615718:src/codealmanac/manual/architecture.md > src/codealmanac/manual/architecture.md
git show 4c615718:src/codealmanac/manual/concepts.md > src/codealmanac/manual/concepts.md
git show 4c615718:src/codealmanac/manual/decisions.md > src/codealmanac/manual/decisions.md
git show 4c615718:src/codealmanac/manual/evidence.md > src/codealmanac/manual/evidence.md
git show 4c615718:src/codealmanac/manual/garden.md > src/codealmanac/manual/garden.md
git show 4c615718:src/codealmanac/manual/how-to-guides.md > src/codealmanac/manual/how-to-guides.md
git show 4c615718:src/codealmanac/manual/how-to-write.md > src/codealmanac/manual/how-to-write.md
git show 4c615718:src/codealmanac/manual/ingest.md > src/codealmanac/manual/ingest.md
git show 4c615718:src/codealmanac/manual/links.md > src/codealmanac/manual/links.md
git show 4c615718:src/codealmanac/manual/reference.md > src/codealmanac/manual/reference.md
git show 4c615718:src/codealmanac/manual/sources.md > src/codealmanac/manual/sources.md
git show 4c615718:src/codealmanac/manual/topics.md > src/codealmanac/manual/topics.md

Init Operation heading         -> Build Operation heading
init operation wording         -> build operation wording where it names the internal operation
pages/<slug>.md paths          -> nested Markdown paths directly under almanac/
pages/ folder wording          -> browseable nested almanac/ tree wording
[[page]] links                 -> Markdown links
[[file/path.py]] file links    -> structured sources evidence or Markdown file links
configured Almanac root aliases -> almanac/ only
sync/capture legacy wording    -> sync is transcript intake; capture is retired
operation list                 -> build, ingest, garden only

class PromptName(StrEnum):
    BASE_KERNEL = "base/kernel.md"
    OPERATION_BUILD = "operations/build.md"
    OPERATION_INGEST = "operations/ingest.md"
    OPERATION_GARDEN = "operations/garden.md"

class ManualDocumentName(StrEnum):
    README = "README.md"
    HOW_TO_WRITE = "how-to-write.md"
    EVIDENCE = "evidence.md"
    LINKS = "links.md"
    TOPICS = "topics.md"
    CONCEPTS = "concepts.md"
    ARCHITECTURE = "architecture.md"
    HOW_TO_GUIDES = "how-to-guides.md"
    DECISIONS = "decisions.md"
    REFERENCE = "reference.md"
    SOURCES = "sources.md"
    INGEST = "ingest.md"
    GARDEN = "garden.md"
 
 
MANUAL_DOCUMENTS: tuple[ManualDocumentName, ...] = (
    ManualDocumentName.README,
    ManualDocumentName.HOW_TO_WRITE,
    ManualDocumentName.EVIDENCE,
    ManualDocumentName.LINKS,
    ManualDocumentName.TOPICS,
    ManualDocumentName.CONCEPTS,
    ManualDocumentName.ARCHITECTURE,
    ManualDocumentName.HOW_TO_GUIDES,
    ManualDocumentName.DECISIONS,
    ManualDocumentName.REFERENCE,
    ManualDocumentName.SOURCES,
    ManualDocumentName.INGEST,
    ManualDocumentName.GARDEN,
)

uv run pytest tests/test_manual.py tests/test_prompt_manual_kushagra_port.py -q
uv run ruff check src/codealmanac/prompts src/codealmanac/manual tests/test_prompt_manual_kushagra_port.py

git add src/codealmanac/prompts src/codealmanac/manual tests/test_manual.py tests/test_prompt_manual_kushagra_port.py
git commit -m "feat: port Kushagra init prompt and manual"

class RunOperation(StrEnum):
    BUILD = "build"
    INGEST = "ingest"
    GARDEN = "garden"

@model_validator(mode="after")
def validate_operation_payload(self) -> "RunSpec":
    if self.version != 1:
        raise ValueError("run spec version must be 1")
    if self.operation == RunOperation.BUILD:
        if len(self.inputs) > 0:
            raise ValueError("build run spec does not accept inputs")
        return self
    if self.operation == RunOperation.INGEST:
        if len(self.inputs) == 0:
            raise ValueError("ingest run spec requires inputs")
        return self
    if self.operation == RunOperation.GARDEN:
        if len(self.inputs) > 0:
            raise ValueError("garden run spec does not accept inputs")
        return self
    raise ValueError(f"unsupported queued run operation: {self.operation.value}")

def test_run_operations_are_only_build_ingest_garden():
    assert tuple(operation.value for operation in RunOperation) == (
        "build",
        "ingest",
        "garden",
    )

assert run.operation == RunOperation.INGEST

uv run pytest tests/test_runs_service.py tests/test_run_queue_workflow.py tests/test_sync_workflow.py tests/test_public_contract.py -q

git add src/codealmanac/services/runs/models.py tests/test_runs_service.py tests/test_run_queue_workflow.py tests/test_sync_workflow.py tests/test_public_contract.py
git commit -m "refactor: restrict wiki operations to build ingest garden"

init
ingest
garden
sync

build
capture
absorb

init.add_argument("path", nargs="?", default=".")
init.add_argument("--name")
init.add_argument("--description", default="")
init.add_argument("--using", choices=tuple(kind.value for kind in HarnessKind))
init.add_argument("--title")
init.add_argument("--guidance")
init.add_argument("--force", action="store_true")
init.add_argument("--background", action="store_true")
init.add_argument("--foreground", action="store_true")
init.add_argument("--json", action="store_true")

def dispatch_init(args: argparse.Namespace, app: CodeAlmanac) -> int:
    request = build_request(args)
    if args.background:
        result = app.workflows.queue.start_build_background(request)
        render_queued_operation(result, json_output=args.json)
        return 0
    result = app.workflows.build.run(request)
    render_build_operation(result)
    return 0

with pytest.raises(SystemExit):
    parser.parse_args(("build",))
assert "invalid choice: 'build'" in capsys.readouterr().err

uv run pytest tests/test_cli.py tests/test_public_contract.py -q
uv run ruff check src/codealmanac/cli tests/test_cli.py tests/test_public_contract.py

git add src/codealmanac/cli tests/test_cli.py tests/test_public_contract.py
git commit -m "feat: route init to build operation"

from pathlib import Path
 
from pydantic import field_validator
 
from codealmanac.core.models import CodeAlmanacModel
from codealmanac.core.text import required_text
from codealmanac.services.harnesses.models import HarnessKind
from codealmanac.services.runs.models import RunId
 
 
class RunBuildRequest(CodeAlmanacModel):
    cwd: Path
    harness: HarnessKind
    wiki: str | None = None
    name: str | None = None
    description: str = ""
    title: str | None = None
    guidance: str | None = None
    force: bool = False
    auto_commit: bool = True
 
    @field_validator("name", "description", "title", "guidance")
    @classmethod
    def require_optional_text(cls, value: str | None) -> str | None:
        if value is None:
            return None
        return required_text(value, "build request text")
 
 
class RunBuildWithRunRequest(RunBuildRequest):
    run_id: RunId

from pathlib import Path
 
from codealmanac.core.models import CodeAlmanacModel
from codealmanac.services.harnesses.models import HarnessRunResult
from codealmanac.services.index.models import IndexRefreshResult
from codealmanac.services.runs.models import RunRecord
from codealmanac.services.workspaces.models import Workspace
from codealmanac.workflows.lifecycle import LifecycleMutationReport
from codealmanac.workflows.lifecycle_commit import LifecycleCommitPolicy
 
 
class BuildPromptPayload(CodeAlmanacModel):
    workspace_name: str
    workspace_root: Path
    almanac_root: Path
    source_control: LifecycleCommitPolicy
    guidance: str | None = None
 
 
class BuildResult(CodeAlmanacModel):
    workspace: Workspace
    run: RunRecord
    harness: HarnessRunResult
    safety: LifecycleMutationReport
    index: IndexRefreshResult

workspaces: WorkspacesService
wiki: WikiService
index: IndexService
runs: RunsService
page_runs: PageRunWorkflow
prompts: PromptRenderer

BUILD_PROMPT_SECTIONS = (
    PromptName.BASE_KERNEL,
    PromptName.OPERATION_BUILD,
)

Runtime context:
{
  "workspace_name": "...",
  "workspace_root": "...",
  "almanac_root": ".../almanac",
  "source_control": {...},
  "guidance": "..."
}

---
title: Getting Started
topics: [getting-started]
sources:
  - type: file
    path: pyproject.toml
---
# Getting Started
 
This wiki starts with the Python package metadata.

uv run pytest tests/test_build_workflow.py tests/test_cli.py -q
uv run ruff check src/codealmanac/workflows/build src/codealmanac/app.py tests/test_build_workflow.py

git add src/codealmanac/workflows/build src/codealmanac/workflows/page_run src/codealmanac/workflows/lifecycle_mutation.py src/codealmanac/app.py tests/test_build_workflow.py tests/test_cli.py
git commit -m "feat: implement model backed build operation"

def queue_build(self, request: RunBuildRequest) -> RunRecord:
    return self.runs.queue(
        QueueRunRequest(
            cwd=request.cwd,
            wiki=request.wiki,
            title=request.title or "Build wiki",
            spec=RunSpec(
                operation=RunOperation.BUILD,
                cwd=request.cwd,
                wiki=request.wiki,
                harness=request.harness,
                title=request.title,
                guidance=request.guidance,
                auto_commit=request.auto_commit,
            ),
        )
    )

def start_build_background(self, request: RunBuildRequest) -> RunQueueStartResult:
    run = self.queue_build(request)
    worker = self.spawn_worker(request.cwd, request.wiki)
    return RunQueueStartResult(run=run, worker=worker)

if spec.operation == RunOperation.BUILD:
    result = self.build.run_with_run(
        RunBuildWithRunRequest(
            cwd=spec.cwd,
            wiki=spec.wiki,
            harness=spec.harness,
            title=spec.title,
            guidance=spec.guidance,
            auto_commit=spec.auto_commit,
            run_id=queued.record.run_id,
        )
    )
    return result.run

uv run pytest tests/test_run_queue_workflow.py tests/test_build_workflow.py tests/test_cli.py -q

git add src/codealmanac/workflows/run_queue src/codealmanac/services/runs/models.py src/codealmanac/cli/dispatch/worker.py src/codealmanac/app.py tests/test_run_queue_workflow.py
git commit -m "feat: queue build operation"

sync quiet local transcripts into ingest runs

return RunIngestRequest(
    cwd=item.candidate.repo_root,
    inputs=(f"transcript:{item.candidate.transcript_path}",),
    harness=request.harness,
    wiki=request.wiki,
    title=sync_ingest_title(item.candidate),
    guidance=sync_ingest_guidance(item),
    auto_commit=request.auto_commit,
)

runs = app.runs.list(ListRunsRequest(cwd=repo))
assert all(run.operation == RunOperation.INGEST for run in runs)

uv run pytest tests/test_sync_workflow.py tests/test_cli.py -q
uv run ruff check src/codealmanac/workflows/sync src/codealmanac/cli tests/test_sync_workflow.py

git add src/codealmanac/workflows/sync src/codealmanac/cli tests/test_sync_workflow.py tests/test_cli.py
git commit -m "refactor: make sync transcript intake only"

sync
garden
update

How should your wikis be updated?

sync agent sessions
garden wiki structure

run them yourself
no wiki schedules

Keep CodeAlmanac itself up to date?

install product updater
new versions arrive automatically

update yourself
no product update schedule

uv run pytest tests/test_automation_service.py tests/test_setup_service.py tests/test_cli.py -q
uv run ruff check src/codealmanac/services/automation src/codealmanac/services/setup src/codealmanac/cli/render/setup.py

git add src/codealmanac/services/automation src/codealmanac/services/setup src/codealmanac/cli/render/setup.py tests/test_automation_service.py tests/test_setup_service.py tests/test_cli.py
git commit -m "fix: separate scheduled tasks from wiki operations"

CodeAlmanac has three internal wiki operations:
 
- `build`: first substantial wiki construction, started by `codealmanac init`
- `ingest`: update the wiki from explicit sources or synced agent transcripts
- `garden`: maintain structure, topics, links, stale claims, and page boundaries
 
`sync` is transcript intake. It scans quiet agent sessions and starts `ingest`
runs. `update` is product maintenance. Neither is a wiki operation.

codealmanac search "<query>"
codealmanac show <page-path>
codealmanac topics
codealmanac health

codealmanac init
codealmanac ingest <source...>
codealmanac garden

codealmanac sync
codealmanac sync status

uv run pytest tests/test_setup_service.py tests/test_public_contract.py -q

git add src/codealmanac/services/setup/agent-guide.md src/codealmanac/integrations/setup/guide.py tests/test_setup_service.py tests/test_public_contract.py
git commit -m "docs: install correct agent operation guide"

`codealmanac init` builds the first wiki for a repo. Internally that run is
recorded as operation `build`.
 
The only internal wiki operations are `build`, `ingest`, and `garden`.

`codealmanac sync` scans quiet local agent transcripts and starts ordinary
`ingest` runs. Sync is intake, not an operation.

`codealmanac setup` is machine-level onboarding. It installs agent instructions,
scheduled wiki maintenance, product updates, and commit policy instructions.
It does not initialize a repo. Run `codealmanac init` inside a repo.

uv run pytest tests/test_public_contract.py -q
rg -n "codealmanac build|almanac capture|\\babsorb\\b|\\.almanac/pages|files:" README.md docs src/codealmanac/manual src/codealmanac/services/setup/agent-guide.md

git add README.md docs/concepts.md CONTRIBUTING.md tests/test_public_contract.py
git commit -m "docs: document init as build operation"

result = run_cli(("init", str(repo), "--using", "codex"))
assert result.exit_code == 0
runs = app.runs.list(ListRunsRequest(cwd=repo))
assert runs[0].operation == RunOperation.BUILD
assert (repo / "almanac/getting-started.md").is_file()

result = run_cli(("sync", "--foreground", "--using", "codex"))
assert result.exit_code == 0
runs = app.runs.list(ListRunsRequest(cwd=repo))
assert all(run.operation == RunOperation.INGEST for run in runs)

Navigate to your repo of choice
codealmanac init

uv run pytest -q
uv run ruff check .
git diff --check

git add tests/test_cli.py tests/test_build_workflow.py tests/test_sync_workflow.py
git commit -m "test: cover operation architecture end to end"

tmp_home=$(mktemp -d)
HOME="$tmp_home" uv run codealmanac setup --target codex --sync-off --garden-off --no-auto-update --yes

cd /path/to/your/repo
codealmanac init

tmp_home=$(mktemp -d)
tmp_repo=$(mktemp -d)
cd "$tmp_repo"
git init
printf '[project]\nname = "sample"\n' > pyproject.toml
HOME="$tmp_home" uv run --directory /Users/rohan/Desktop/Projects/codealmanac codealmanac init --using codex --foreground

uv run pytest tests/test_sync_workflow.py -q

rg -n "RunOperation\\.SYNC|operation: sync|operation=RunOperation\\.SYNC|codealmanac build|almanac capture|\\babsorb\\b|\\.almanac/pages|files:" src tests README.md docs notes.md implementation-tickets.md

git add .
git commit -m "fix: align smoke behavior with three operations"

uv run pytest -q
uv run ruff check .
git diff --check
uv build --out-dir dist
uvx twine check dist/*

git log --oneline -12
git status --short --branch